luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '3155-girepository-docs-cleanups' into 'main'

Browse Source 
girepository: Port documentation to gi-docgen and update

See merge request GNOME/glib!3767
This commit is contained in:
Philip Withnall 2023-12-18 16:58:40 +00:00
commit 0e475a6e11
46 changed files with 1511 additions and 986 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
girepository/docs.c
View File

@ -1,35 +0,0 @@
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
* GObject introspection: Dump introspection data
*
* Copyright (C) 2013 Dieter Verfaillie <dieterv@optionexplicit.be>
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
/* This file collects documentation for macros, typedefs and
* the like, which have no good home in any of the 'real' source
* files.
*/
/**
* SECTION:gicommontypes
* @title: Common Types
* @short_description: TODO
*
* TODO
*/

96
girepository/giarginfo.c
View File

@ -35,23 +35,24 @@
/* GIArgInfo functions */
/**
* SECTION:giarginfo
* @title: GIArgInfo
* @short_description: Struct representing an argument
* GIArgInfo:
*
* GIArgInfo represents an argument of a callable.
* `GIArgInfo` represents an argument of a callable.
*
* An argument is always part of a #GICallableInfo.
* An argument is always part of a [class@GIRepository.CallableInfo].
*
* Since: 2.80
*/
/**
* gi_arg_info_get_direction:
* @info: a #GIArgInfo
*
* Obtain the direction of the argument. Check #GIDirection for possible
* direction values.
* Obtain the direction of the argument. Check [type@GIRepository.Direction]
* for possible direction values.
*
* Returns: the direction
* Returns: The direction
* Since: 2.80
*/
GIDirection
gi_arg_info_get_direction (GIArgInfo *info)
@ -79,7 +80,8 @@ gi_arg_info_get_direction (GIArgInfo *info)
* Obtain if the argument is a return value. It can either be a
* parameter or a return value.
*
* Returns: %TRUE if it is a return value
* Returns: `TRUE` if it is a return value
* Since: 2.80
*/
gboolean
gi_arg_info_is_return_value (GIArgInfo *info)
@ -100,11 +102,14 @@ gi_arg_info_is_return_value (GIArgInfo *info)
* @info: a #GIArgInfo
*
* Obtain if the argument is a pointer to a struct or object that will
* receive an output of a function. The default assumption for
* %GI_DIRECTION_OUT arguments which have allocation is that the
* callee allocates; if this is %TRUE, then the caller must allocate.
* receive an output of a function.
*
* Returns: %TRUE if caller is required to have allocated the argument
* The default assumption for `GI_DIRECTION_OUT` arguments which have allocation
* is that the callee allocates; if this is `TRUE`, then the caller must
* allocate.
*
* Returns: `TRUE` if caller is required to have allocated the argument
* Since: 2.80
*/
gboolean
gi_arg_info_is_caller_allocates (GIArgInfo *info)
@ -124,10 +129,13 @@ gi_arg_info_is_caller_allocates (GIArgInfo *info)
* gi_arg_info_is_optional:
* @info: a #GIArgInfo
*
* Obtain if the argument is optional. For 'out' arguments this means
* that you can pass %NULL in order to ignore the result.
* Obtain if the argument is optional.
*
* Returns: %TRUE if it is an optional argument
* For ‘out’ arguments this means that you can pass `NULL` in order to ignore
* the result.
*
* Returns: `TRUE` if it is an optional argument
* Since: 2.80
*/
gboolean
gi_arg_info_is_optional (GIArgInfo *info)
@ -147,13 +155,15 @@ gi_arg_info_is_optional (GIArgInfo *info)
* gi_arg_info_may_be_null:
* @info: a #GIArgInfo
*
* Obtain if the type of the argument includes the possibility of %NULL.
* For 'in' values this means that %NULL is a valid value. For 'out'
* values, this means that %NULL may be returned.
* Obtain if the type of the argument includes the possibility of `NULL`.
*
* See also gi_arg_info_is_optional().
* For ‘in’ values this means that `NULL` is a valid value. For ‘out’
* values, this means that `NULL` may be returned.
*
* Returns: %TRUE if the value may be %NULL
* See also [method@GIRepository.ArgInfo.is_optional].
*
* Returns: `TRUE` if the value may be `NULL`
* Since: 2.80
*/
gboolean
gi_arg_info_may_be_null (GIArgInfo *info)
@ -175,7 +185,7 @@ gi_arg_info_may_be_null (GIArgInfo *info)
*
* Obtain if an argument is only useful in C.
*
* Returns: %TRUE if argument is only useful in C.
* Returns: `TRUE` if argument is only useful in C.
* Since: 2.80
*/
gboolean
@ -197,9 +207,10 @@ gi_arg_info_is_skip (GIArgInfo *info)
* @info: a #GIArgInfo
*
* Obtain the ownership transfer for this argument.
* #GITransfer contains a list of possible values.
* [type@GIRepository.Transfer] contains a list of possible values.
*
* Returns: the transfer
* Returns: The transfer
* Since: 2.80
*/
GITransfer
gi_arg_info_get_ownership_transfer (GIArgInfo *info)
@ -224,12 +235,15 @@ gi_arg_info_get_ownership_transfer (GIArgInfo *info)
* gi_arg_info_get_scope:
* @info: a #GIArgInfo
*
* Obtain the 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.
* #GIScopeType contains a list of possible values.
* Obtain the scope type for this argument.
*
* Returns: the scope type
* The scope type explains how a callback is going to be invoked, most
* importantly when the resources required to invoke it can be freed.
*
* [type@GIRepository.ScopeType] contains a list of possible values.
*
* Returns: The scope type
* Since: 2.80
*/
GIScopeType
gi_arg_info_get_scope (GIArgInfo *info)
@ -252,7 +266,8 @@ gi_arg_info_get_scope (GIArgInfo *info)
* Obtain the index of the user data argument. This is only valid
* for arguments which are callbacks.
*
* Returns: index of the user data argument or -1 if there is none
* Returns: Index of the user data argument or `-1` if there is none
* Since: 2.80
*/
gint
gi_arg_info_get_closure_index (GIArgInfo *info)
@ -272,10 +287,12 @@ gi_arg_info_get_closure_index (GIArgInfo *info)
* gi_arg_info_get_destroy_index:
* @info: a #GIArgInfo
*
* Obtains the index of the #GDestroyNotify argument. This is only valid
* for arguments which are callbacks.
* Obtains the index of the [type@GLib.DestroyNotify] argument. This is only
* valid for arguments which are callbacks.
*
* Returns: index of the #GDestroyNotify argument or -1 if there is none
* Returns: Index of the [type@GLib.DestroyNotify] argument or `-1` if there is
* none
* Since: 2.80
*/
gint
gi_arg_info_get_destroy_index (GIArgInfo *info)
@ -297,9 +314,10 @@ gi_arg_info_get_destroy_index (GIArgInfo *info)
*
* Obtain the type information for @info.
*
* Returns: (transfer full): the #GITypeInfo holding the type
* information for @info, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.TypeInfo] holding the type
* information for @info, free it with [method@GIRepository.BaseInfo.unref]
* when done
* Since: 2.80
*/
GITypeInfo *
gi_arg_info_get_type_info (GIArgInfo *info)
@ -318,10 +336,12 @@ gi_arg_info_get_type_info (GIArgInfo *info)
* @type: (out caller-allocates): Initialized with information about type of @info
*
* Obtain information about a the type of given argument @info; this
* function is a variant of gi_arg_info_get_type_info() designed for stack
* allocation.
* function is a variant of [method@GIRepository.ArgInfo.get_type_info] designed
* for stack allocation.
*
* The initialized @type must not be referenced after @info is deallocated.
*
* Since: 2.80
*/
void
gi_arg_info_load_type (GIArgInfo *info,

6
girepository/giarginfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_ARG_INFO
* GI_IS_ARG_INFO:
* @info: an info structure
*
* Checks if @info is a GIArgInfo.
* Checks if @info is a [class@GIRepository.ArgInfo].
*
* Since: 2.80
*/
#define GI_IS_ARG_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_ARG)

7
girepository/gibaseinfo-private.h
View File

@ -30,13 +30,6 @@
G_BEGIN_DECLS
/* Keep this in sync with the GIInfoType enumeration.
*
* We don't add an "n-types" value to avoid having to handle
* it in every single switch.
*/
#define GI_INFO_TYPE_N_TYPES (GI_INFO_TYPE_REGISTERED_TYPE + 1)
#define GI_IS_BASE_INFO_TYPE(info,type) \
(G_TYPE_INSTANCE_GET_CLASS ((info), GI_TYPE_BASE_INFO, GIBaseInfoClass)->info_type == (type))

160
girepository/gibaseinfo.c
View File

@ -341,24 +341,41 @@ gi_info_new_full (GIInfoType type,
/**
* gi_info_new:
* @type: TODO
* @container: TODO
* @typelib: TODO
* @offset: TODO
* @type: type of the info to create
* @container: (nullable): info which contains this one
* @typelib: typelib containing the info
* @offset: offset of the info within @typelib, in bytes
*
* TODO
* Create a new #GIBaseInfo representing an object of the given @type from
* @offset of @typelib.
*
* Returns: (transfer full): TODO
* Returns: (transfer full): The new #GIBaseInfo, unref with
* [method@GIRepository.BaseInfo.unref]
* Since: 2.80
*/
GIBaseInfo *
gi_info_new (GIInfoType type,
GIBaseInfo *container,
GITypelib *typelib,
GITypelib *typelib,
guint32 offset)
{
return gi_info_new_full (type, ((GIRealInfo*)container)->repository, container, typelib, offset);
}
/*< private >
* gi_info_init:
* @info: (out caller-allocates): caller-allocated #GIRealInfo to populate
* @type: type of the info to create
* @repository: repository the info is in
* @container: (nullable): info which contains this one
* @typelib: typelib containing the info
* @offset: offset of the info within @typelib, in bytes
*
* Initialise a stack-allocated #GIBaseInfo representing an object of the given
* @type from @offset of @typelib.
*
* Since: 2.80
*/
void
gi_info_init (GIRealInfo *info,
GIInfoType type,
@ -445,58 +462,48 @@ gi_type_info_init (GIBaseInfo *info,
/* GIBaseInfo functions */
/**
* SECTION:gibaseinfo
* @title: GIBaseInfo
* @short_description: Base struct for all GITypelib structs
* GIBaseInfo:
*
* GIBaseInfo is the common base struct of all other Info structs
* accessible through the #GIRepository API.
* `GIBaseInfo` is the common base struct of all other Info structs
* accessible through the [class@GIRepository.Repository] API.
*
* All info structures can be cast to a #GIBaseInfo, for instance:
* All info structures can be cast to a `GIBaseInfo`, for instance:
*
* |[<!-- language="C" -->
* GIFunctionInfo *function_info = ...;
* ```c
* GIFunctionInfo *function_info = …;
* GIBaseInfo *info = (GIBaseInfo *) function_info;
* ]|
* ```
*
* Most #GIRepository APIs returning a #GIBaseInfo is actually
* creating a new struct; in other words, gi_base_info_unref() has to
* be called when done accessing the data.
* Most [class@GIRepository.Repository] APIs returning a `GIBaseInfo` are
* actually creating a new struct; in other words,
* [method@GIRepository.BaseInfo.unref] has to be called when done accessing the
* data.
*
* #GIBaseInfo structuress are normally accessed by calling either
* gi_repository_find_by_name(), gi_repository_find_by_gtype() or
* gi_repository_get_info().
* `GIBaseInfo` structuress are normally accessed by calling either
* [method@GIRepository.Repository.find_by_name],
* [method@GIRepository.Repository.find_by_gtype] or
* [method@GIRepository.get_info].
*
* |[<!-- language="C" -->
* ```c
* GIBaseInfo *button_info =
* gi_repository_find_by_name (NULL, "Gtk", "Button");
*
* // ... use button_info ...
* // use button_info…
*
* gi_base_info_unref (button_info);
* ]|
* ```
*
* ## Hierarchy
*
* |[<!-- language="plain" -->
* GIBaseInfo
* +---- GIArgInfo
* +---- GICallableInfo
* +---- GIConstantInfo
* +---- GIFieldInfo
* +---- GIPropertyInfo
* +---- GIRegisteredTypeInfo
* +---- GITypeInfo
* ]|
* Since: 2.80
*/
/**
* gi_base_info_ref: (skip)
* gi_base_info_ref:
* @info: a #GIBaseInfo
*
* Increases the reference count of @info.
*
* Returns: the same @info.
* Returns: (transfer full): the same @info.
* Since: 2.80
*/
GIBaseInfo *
gi_base_info_ref (GIBaseInfo *info)
@ -510,11 +517,13 @@ gi_base_info_ref (GIBaseInfo *info)
}
/**
* gi_base_info_unref: (skip)
* @info: a #GIBaseInfo
* gi_base_info_unref:
* @info: (transfer full): a #GIBaseInfo
*
* Decreases the reference count of @info. When its reference count
* drops to 0, the info is freed.
*
* Since: 2.80
*/
void
gi_base_info_unref (GIBaseInfo *info)
@ -531,9 +540,10 @@ gi_base_info_unref (GIBaseInfo *info)
* gi_base_info_get_info_type:
* @info: a #GIBaseInfo
*
* Obtain the info type of the GIBaseInfo.
* Obtain the info type of the `GIBaseInfo`.
*
* Returns: the info type of @info
* Since: 2.80
*/
GIInfoType
gi_base_info_get_info_type (GIBaseInfo *info)
@ -545,11 +555,14 @@ gi_base_info_get_info_type (GIBaseInfo *info)
* gi_base_info_get_name:
* @info: a #GIBaseInfo
*
* Obtain the name of the @info. What the name represents depends on
* the #GIInfoType of the @info. For instance for #GIFunctionInfo it is
* the name of the function.
* Obtain the name of the @info.
*
* Returns: the name of @info or %NULL if it lacks a name.
* What the name represents depends on the [type@GIRepository.InfoType] of the
* @info. For instance for [class@GIRepository.FunctionInfo] it is the name of
* the function.
*
* Returns: (nullable): the name of @info or `NULL` if it lacks a name.
* Since: 2.80
*/
const gchar *
gi_base_info_get_name (GIBaseInfo *info)
@ -647,6 +660,7 @@ gi_base_info_get_name (GIBaseInfo *info)
* Obtain the namespace of @info.
*
* Returns: the namespace
* Since: 2.80
*/
const gchar *
gi_base_info_get_namespace (GIBaseInfo *info)
@ -671,9 +685,10 @@ gi_base_info_get_namespace (GIBaseInfo *info)
* @info: a #GIBaseInfo
*
* Obtain whether the @info is represents a metadata which is
* deprecated or not.
* deprecated.
*
* Returns: %TRUE if deprecated
* Returns: `TRUE` if deprecated
* Since: 2.80
*/
gboolean
gi_base_info_is_deprecated (GIBaseInfo *info)
@ -740,7 +755,9 @@ gi_base_info_is_deprecated (GIBaseInfo *info)
*
* Retrieve an arbitrary attribute associated with this node.
*
* Returns: The value of the attribute, or %NULL if no such attribute exists
* Returns: (nullable): The value of the attribute, or `NULL` if no such
* attribute exists
* Since: 2.80
*/
const gchar *
gi_base_info_get_attribute (GIBaseInfo *info,
@ -772,7 +789,7 @@ cmp_attribute (const void *av,
return 1;
}
/*
/*< private >
* _attribute_blob_find_first:
* @GIBaseInfo: A #GIBaseInfo.
* @blob_offset: The offset for the blob to find the first attribute for.
@ -780,7 +797,8 @@ cmp_attribute (const void *av,
* Searches for the first #AttributeBlob for @blob_offset and returns
* it if found.
*
* Returns: A pointer to #AttributeBlob or %NULL if not found.
* Returns: (transfer none): A pointer to #AttributeBlob or `NULL` if not found.
* Since: 2.80
*/
AttributeBlob *
_attribute_blob_find_first (GIBaseInfo *info,
@ -813,13 +831,15 @@ _attribute_blob_find_first (GIBaseInfo *info,
/**
* gi_base_info_iterate_attributes:
* @info: a #GIBaseInfo
* @iterator: (inout): a #GIAttributeIter structure, must be initialized; see below
* @iterator: (inout): a [type@GIRepository.AttributeIter] structure, must be
* initialized; see below
* @name: (out) (transfer none): Returned name, must not be freed
* @value: (out) (transfer none): Returned name, must not be freed
*
* Iterate over all attributes associated with this node. The iterator
* structure is typically stack allocated, and must have its first
* member initialized to %NULL. Attributes are arbitrary namespaced key–value
* Iterate over all attributes associated with this node.
*
* The iterator structure is typically stack allocated, and must have its first
* member initialized to `NULL`. Attributes are arbitrary namespaced key–value
* pairs which can be attached to almost any item. They are intended for use
* by software higher in the toolchain than bindings, and are distinct from
* normal GIR annotations.
@ -827,7 +847,7 @@ _attribute_blob_find_first (GIBaseInfo *info,
* Both the @name and @value should be treated as constants
* and must not be freed.
*
* |[<!-- language="C" -->
* ```c
* void
* print_attributes (GIBaseInfo *info)
* {
@ -839,9 +859,10 @@ _attribute_blob_find_first (GIBaseInfo *info,
* g_print ("attribute name: %s value: %s", name, value);
* }
* }
* ]|
* ```
*
* Returns: %TRUE if there are more attributes
* Returns: `TRUE` if there are more attributes
* Since: 2.80
*/
gboolean
gi_base_info_iterate_attributes (GIBaseInfo *info,
@ -875,11 +896,14 @@ gi_base_info_iterate_attributes (GIBaseInfo *info,
* gi_base_info_get_container:
* @info: a #GIBaseInfo
*
* Obtain the container of the @info. The container is the parent
* GIBaseInfo. For instance, the parent of a #GIFunctionInfo is an
* #GIObjectInfo or #GIInterfaceInfo.
* Obtain the container of the @info.
*
* The container is the parent `GIBaseInfo`. For instance, the parent of a
* [class@GIRepository.FunctionInfo] is an [class@GIRepository.ObjectInfo] or
* [class@GIRepository.InterfaceInfo].
*
* Returns: (transfer none): the container
* Since: 2.80
*/
GIBaseInfo *
gi_base_info_get_container (GIBaseInfo *info)
@ -893,7 +917,8 @@ gi_base_info_get_container (GIBaseInfo *info)
*
* Obtain the typelib this @info belongs to
*
* Returns: (transfer none): the typelib.
* Returns: (transfer none): the typelib
* Since: 2.80
*/
GITypelib *
gi_base_info_get_typelib (GIBaseInfo *info)
@ -906,13 +931,14 @@ gi_base_info_get_typelib (GIBaseInfo *info)
* @info1: a #GIBaseInfo
* @info2: a #GIBaseInfo
*
* Compare two #GIBaseInfo.
* Compare two `GIBaseInfo`s.
*
* Using pointer comparison is not practical since many functions return
* different instances of #GIBaseInfo that refers to the same part of the
* TypeLib; use this function instead to do #GIBaseInfo comparisons.
* different instances of `GIBaseInfo` that refers to the same part of the
* TypeLib; use this function instead to do `GIBaseInfo` comparisons.
*
* Returns: %TRUE if and only if @info1 equals @info2.
* Returns: `TRUE` if and only if @info1 equals @info2.
* Since: 2.80
*/
gboolean
gi_base_info_equal (GIBaseInfo *info1, GIBaseInfo *info2)
@ -922,5 +948,3 @@ gi_base_info_equal (GIBaseInfo *info1, GIBaseInfo *info2)
GIRealInfo *rinfo2 = (GIRealInfo*)info2;
return rinfo1->typelib->data + rinfo1->offset == rinfo2->typelib->data + rinfo2->offset;
}

4
girepository/gibaseinfo.h
View File

@ -38,7 +38,9 @@ G_BEGIN_DECLS
* GIAttributeIter:
*
* An opaque structure used to iterate over attributes
* in a #GIBaseInfo struct.
* in a [class@GIRepository.BaseInfo] struct.
*
* Since: 2.80
*/
typedef struct {
/*< private >*/

184
girepository/gicallableinfo.c
View File

@ -38,20 +38,20 @@
/* GICallableInfo functions */
/**
* SECTION:gicallableinfo
* @title: GICallableInfo
* @short_description: Struct representing a callable
* GICallableInfo:
*
* GICallableInfo represents an entity which is callable.
* `GICallableInfo` represents an entity which is callable.
*
* Examples of callable are:
*
* - functions (#GIFunctionInfo)
* - virtual functions (#GIVFuncInfo)
* - callbacks (#GICallbackInfo).
* - functions ([class@GIRepository.FunctionInfo])
* - virtual functions ([class@GIRepository.VFuncInfo])
* - callbacks ([class@GIRepository.CallbackInfo]).
*
* A callable has a list of arguments (#GIArgInfo), a return type,
* direction and a flag which decides if it returns null.
* A callable has a list of arguments ([class@GIRepository.ArgInfo]), a return
* type, direction and a flag which decides if it returns `NULL`.
*
* Since: 2.80
*/
static guint32
@ -86,10 +86,10 @@ signature_offset (GICallableInfo *info)
* gi_callable_info_can_throw_gerror:
* @info: a #GICallableInfo
*
* TODO
* Whether the callable can throw a [type@GLib.Error]
*
* Returns: `TRUE` if this `GICallableInfo` can throw a [type@GLib.Error]
* Since: 2.80
* Returns: %TRUE if this #GICallableInfo can throw a #GError
*/
gboolean
gi_callable_info_can_throw_gerror (GICallableInfo *info)
@ -131,17 +131,18 @@ gi_callable_info_can_throw_gerror (GICallableInfo *info)
* gi_callable_info_is_method:
* @info: a #GICallableInfo
*
* Determines if the callable info is a method. For #GIVFuncInfo<!-- -->s,
* #GICallbackInfo<!-- -->s, and #GISignalInfo<!-- -->s,
* this is always true. Otherwise, this looks at the %GI_FUNCTION_IS_METHOD
* flag on the #GIFunctionInfo.
* Determines if the callable info is a method.
*
* Concretely, this function returns whether gi_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 "self"
* or "this" object.
* For [class@GIRepository.VFuncInfo]s, [class@GIRepository.CallbackInfo]s, and
* [class@GIRepository.SignalInfo]s, this is always true. Otherwise, this looks
* at the `GI_FUNCTION_IS_METHOD` flag on the [class@GIRepository.FunctionInfo].
*
* Returns: %TRUE if @info is a method, %FALSE otherwise
* Concretely, this function returns whether
* [method@GIRepository.CallableInfo.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 `self` or `this` object.
*
* Returns: `TRUE` if @info is a method, `FALSE` otherwise
* Since: 2.80
*/
gboolean
@ -169,10 +170,11 @@ gi_callable_info_is_method (GICallableInfo *info)
* gi_callable_info_get_return_type:
* @info: a #GICallableInfo
*
* Obtain the return type of a callable item as a #GITypeInfo.
* Obtain the return type of a callable item as a [class@GIRepository.TypeInfo].
*
* Returns: (transfer full): the #GITypeInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): the [class@GIRepository.TypeInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GITypeInfo *
gi_callable_info_get_return_type (GICallableInfo *info)
@ -188,17 +190,18 @@ gi_callable_info_get_return_type (GICallableInfo *info)
return gi_type_info_new ((GIBaseInfo*)info, rinfo->typelib, offset);
}
/**
* gi_callable_info_load_return_type:
* @info: a #GICallableInfo
* @type: (out caller-allocates): Initialized with return type of @info
*
* Obtain information about a return value of callable; this
* function is a variant of gi_callable_info_get_return_type() designed for stack
* allocation.
* function is a variant of [method@GIRepository.CallableInfo.get_return_type]
* designed for stack allocation.
*
* The initialized @type must not be referenced after @info is deallocated.
*
* Since: 2.80
*/
void
gi_callable_info_load_return_type (GICallableInfo *info,
@ -219,9 +222,10 @@ gi_callable_info_load_return_type (GICallableInfo *info,
* gi_callable_info_may_return_null:
* @info: a #GICallableInfo
*
* See if a callable could return %NULL.
* See if a callable could return `NULL`.
*
* Returns: %TRUE if callable could return %NULL
* Returns: `TRUE` if callable could return `NULL`
* Since: 2.80
*/
gboolean
gi_callable_info_may_return_null (GICallableInfo *info)
@ -241,9 +245,10 @@ gi_callable_info_may_return_null (GICallableInfo *info)
* gi_callable_info_skip_return:
* @info: a #GICallableInfo
*
* See if a callable's return value is only useful in C.
* See if a callable’s return value is only useful in C.
*
* Returns: %TRUE if return value is only useful in C.
* Returns: `TRUE` if return value is only useful in C.
* Since: 2.80
*/
gboolean
gi_callable_info_skip_return (GICallableInfo *info)
@ -264,9 +269,11 @@ gi_callable_info_skip_return (GICallableInfo *info)
* @info: a #GICallableInfo
*
* See whether the caller owns the return value of this callable.
* #GITransfer contains a list of possible transfer values.
*
* [type@GIRepository.Transfer] contains a list of possible transfer values.
*
* Returns: the transfer mode for the return value of the callable
* Since: 2.80
*/
GITransfer
gi_callable_info_get_caller_owns (GICallableInfo *info)
@ -292,10 +299,11 @@ gi_callable_info_get_caller_owns (GICallableInfo *info)
* @info: a #GICallableInfo
*
* Obtains the ownership transfer for the instance argument.
* #GITransfer contains a list of possible transfer values.
*
* Since: 2.80
* [type@GIRepository.Transfer] contains a list of possible transfer values.
*
* Returns: the transfer mode of the instance argument
* Since: 2.80
*/
GITransfer
gi_callable_info_get_instance_ownership_transfer (GICallableInfo *info)
@ -318,9 +326,10 @@ gi_callable_info_get_instance_ownership_transfer (GICallableInfo *info)
* gi_callable_info_get_n_args:
* @info: a #GICallableInfo
*
* Obtain the number of arguments (both IN and OUT) for this callable.
* Obtain the number of arguments (both ‘in’ and ‘out’) for this callable.
*
* Returns: The number of arguments this callable expects.
* Since: 2.80
*/
guint
gi_callable_info_get_n_args (GICallableInfo *info)
@ -345,8 +354,9 @@ gi_callable_info_get_n_args (GICallableInfo *info)
*
* Obtain information about a particular argument of this callable.
*
* Returns: (transfer full): the #GIArgInfo. Free it with
* gi_base_info_unref() when done.
* Returns: (transfer full): the [class@GIRepository.ArgInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIArgInfo *
gi_callable_info_get_arg (GICallableInfo *info,
@ -373,10 +383,12 @@ gi_callable_info_get_arg (GICallableInfo *info,
* @arg: (out caller-allocates): Initialize with argument number @n
*
* Obtain information about a particular argument of this callable; this
* function is a variant of gi_callable_info_get_arg() designed for stack
* allocation.
* function is a variant of [method@GIRepository.CallableInfo.get_arg] designed
* for stack allocation.
*
* The initialized @arg must not be referenced after @info is deallocated.
*
* Since: 2.80
*/
void
gi_callable_info_load_arg (GICallableInfo *info,
@ -404,7 +416,9 @@ gi_callable_info_load_arg (GICallableInfo *info,
*
* Retrieve an arbitrary attribute associated with the return value.
*
* Returns: The value of the attribute, or %NULL if no such attribute exists
* Returns: (nullable): The value of the attribute, or `NULL` if no such
* attribute exists
* Since: 2.80
*/
const gchar *
gi_callable_info_get_return_attribute (GICallableInfo *info,
@ -424,21 +438,24 @@ gi_callable_info_get_return_attribute (GICallableInfo *info,
/**
* gi_callable_info_iterate_return_attributes:
* @info: a #GICallableInfo
* @iterator: (inout): a #GIAttributeIter structure, must be initialized; see below
* @iterator: (inout): a [type@GIRepository.AttributeIter] structure, must be
* initialized; see below
* @name: (out) (transfer none): Returned name, must not be freed
* @value: (out) (transfer none): Returned name, must not be freed
*
* Iterate over all attributes associated with the return value. The
* iterator structure is typically stack allocated, and must have its
* first member initialized to %NULL.
* Iterate over all attributes associated with the return value.
*
* The iterator structure is typically stack allocated, and must have its
* first member initialized to `NULL`.
*
* Both the @name and @value should be treated as constants
* and must not be freed.
*
* See gi_base_info_iterate_attributes() for an example of how to use a
* similar API.
* See [method@GIRepository.BaseInfo.iterate_attributes] for an example of how
* to use a similar API.
*
* Returns: %TRUE if there are more attributes
* Returns: `TRUE` if there are more attributes
* Since: 2.80
*/
gboolean
gi_callable_info_iterate_return_attributes (GICallableInfo *info,
@ -473,22 +490,23 @@ gi_callable_info_iterate_return_attributes (GICallableInfo *info,
/**
* gi_type_tag_extract_ffi_return_value:
* @return_tag: #GITypeTag of the return value
* @interface_type: #GIInfoType of the underlying interface type
* @ffi_value: pointer to #GIFFIReturnValue union containing the return value
* from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated #GIArgument
* @return_tag: [type@GIRepository.TypeTag] of the return value
* @interface_type: [type@GIRepository.InfoType] of the underlying interface type
* @ffi_value: pointer to [type@GIRepository.FFIReturnValue] union containing
* the return value from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated
* [class@GIRepository.Argument]
*
* Extract the correct bits from an `ffi_arg` return value into
* GIArgument.
* [class@GIRepository.Argument].
*
* See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
*
* Also see `ffi_call(3)`: the storage requirements for return values
* are "special".
* Also see [`ffi_call()`](man:ffi_call(3)): the storage requirements for return
* values are ‘special’.
*
* The @interface_type argument only applies if @return_tag is
* %GI_TYPE_TAG_INTERFACE. Otherwise it is ignored.
* `GI_TYPE_TAG_INTERFACE`. Otherwise it is ignored.
*
* Since: 2.80
*/
@ -550,23 +568,26 @@ gi_type_tag_extract_ffi_return_value (GITypeTag return_tag,
/**
* gi_type_info_extract_ffi_return_value:
* @return_info: #GITypeInfo describing the return type
* @ffi_value: pointer to #GIFFIReturnValue union containing the return value
* from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated #GIArgument
* @return_info: [type@GIRepository.TypeInfo] describing the return type
* @ffi_value: pointer to [type@GIRepository.FFIReturnValue] union containing
* the return value from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated
* [class@GIRepository.Argument]
*
* Extract the correct bits from an `ffi_arg` return value into
* #GIArgument.
* [class@GIRepository.Argument].
*
* See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
*
* Also see `ffi_call(3)`: the storage requirements for return values
* are "special".
* Also see [`ffi_call()`](man:ffi_call(3)): the storage requirements for return
* values are ‘special’.
*
* Since: 2.80
*/
void
gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
GIFFIReturnValue *ffi_value,
GIArgument *arg)
gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
GIFFIReturnValue *ffi_value,
GIArgument *arg)
{
GITypeTag return_tag = gi_type_info_get_tag (return_info);
GIInfoType interface_type = GI_INFO_TYPE_INVALID;
@ -584,18 +605,29 @@ gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
/**
* gi_callable_info_invoke:
* @info: TODO
* @function: TODO
* @in_args: (array length=n_in_args): TODO
* @n_in_args: TODO
* @out_args: (array length=n_out_args): TODO
* @n_out_args: TODO
* @return_value: TODO
* @is_method: TODO
* @throws: TODO
* @error: TODO
* @info: a #GICallableInfo
* @function: function pointer to call
* @in_args: (array length=n_in_args): array of ‘in’ arguments
* @n_in_args: number of arguments in @in_args
* @out_args: (array length=n_out_args): array of ‘out’ arguments allocated by
* the caller, to be populated with outputted values
* @n_out_args: number of arguments in @out_args
* @return_value: (out caller-allocates) (not optional) (nullable): return
* location for the return value from the callable; `NULL` may be returned if
* the callable returns that
* @is_method: `TRUE` if @info is a method
* @throws: `TRUE` if @info may throw a [type@GLib.Error]
* @error: return location for a [type@GLib.Error], or `NULL`
*
* TODO
* Invoke the given `GICallableInfo` by calling the given @function pointer.
*
* The set of arguments passed to @function will be constructed according to the
* introspected type of the `GICallableInfo`, using @in_args, @out_args,
* @is_method, @throws and @error.
*
* Returns: `TRUE` if the callable was executed successfully and didn’t throw
* a [type@GLib.Error]; `FALSE` if @error is set
* Since: 2.80
*/
gboolean
gi_callable_info_invoke (GICallableInfo *info,

6
girepository/gicallableinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_CALLABLE_INFO
* GI_IS_CALLABLE_INFO:
* @info: an info structure
*
* Checks if @info is a #GICallableInfo or derived from it.
* Checks if @info is a [class@GIRepository.CallableInfo] or derived from it.
*
* Since: 2.80
*/
#define GI_IS_CALLABLE_INFO(info) \
((gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FUNCTION) || \

8
girepository/gicallbackinfo.c
View File

@ -35,11 +35,11 @@
#include "gicallbackinfo.h"
/**
* SECTION:gicallback
* @title: GICallbackInfo
* @short_description: Struct representing a callback
* GICallbackInfo:
*
* GICallbackInfo represents a callback.
* `GICallbackInfo` represents a callback.
*
* Since: 2.80
*/
void

6
girepository/gicallbackinfo.h
View File

@ -32,10 +32,12 @@
G_BEGIN_DECLS
/**
* GI_IS_CALLBACK_INFO
* GI_IS_CALLBACK_INFO:
* @info: an info structure
*
* Checks if @info is a #GICallbackInfo or derived from it.
* Checks if @info is a [class@GIRepository.CallbackInfo] or derived from it.
*
* Since: 2.80
*/
#define GI_IS_CALLBACK_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_CALLBACK)

40
girepository/giconstantinfo.c
View File

@ -34,26 +34,26 @@
#include "giconstantinfo.h"
/**
* SECTION:giconstantinfo
* @title: GIConstantInfo
* @short_description: Struct representing a constant
* GIConstantInfo:
*
* GIConstantInfo represents a constant.
* `GIConstantInfo` represents a constant.
*
* A constant has a type associated which can be obtained by calling
* gi_constant_info_get_type_info() and a value, which can be obtained by
* calling gi_constant_info_get_value().
* A constant has a type associated – which can be obtained by calling
* [method@GIRepository.ConstantInfo.get_type_info] – and a value – which can be
* obtained by calling [method@GIRepository.ConstantInfo.get_value].
*
* Since: 2.80
*/
/**
* gi_constant_info_get_type_info:
* @info: a #GIConstantInfo
*
* Obtain the type of the constant as a #GITypeInfo.
* Obtain the type of the constant as a [class@GIRepository.TypeInfo].
*
* Returns: (transfer full): the #GITypeInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.TypeInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GITypeInfo *
gi_constant_info_get_type_info (GIConstantInfo *info)
@ -74,7 +74,7 @@ gi_constant_info_get_type_info (GIConstantInfo *info)
* @info: a #GIConstantInfo
* @value: the argument
*
* Free the value returned from gi_constant_info_get_value().
* Free the value returned from [method@GIRepository.ConstantInfo.get_value].
*
* Since: 2.80
*/
@ -101,14 +101,20 @@ gi_constant_info_free_value (GIConstantInfo *info,
/**
* gi_constant_info_get_value: (skip)
* @info: a #GIConstantInfo
* @value: (out): an argument
* @value: (out caller-allocates): an argument
*
* Obtain the value associated with the #GIConstantInfo and store it in the
* @value parameter. @argument needs to be allocated before passing it in.
* The size of the constant value stored in @argument will be returned.
* Free the value with gi_constant_info_free_value().
* Obtain the value associated with the `GIConstantInfo` and store it in the
* @value parameter.
*
* @argument needs to be allocated before passing it in.
*
* The size of the constant value (in bytes) stored in @argument will be
* returned.
*
* Free the value with [method@GIRepository.ConstantInfo.free_value].
*
* Returns: size of the constant, in bytes
* Since: 2.80
*/
gsize
gi_constant_info_get_value (GIConstantInfo *info,

6
girepository/giconstantinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_CONSTANT_INFO
* GI_IS_CONSTANT_INFO:
* @info: an info structure
*
* Checks if @info is a #GIConstantInfo.
* Checks if @info is a [class@GIRepository.ConstantInfo].
*
* Since: 2.80
*/
#define GI_IS_CONSTANT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_CONSTANT)

47
girepository/gienuminfo.c
View File

@ -33,17 +33,17 @@
#include "gienuminfo.h"
/**
* SECTION:gienuminfo
* @title: GIEnumInfo
* @short_description: Structs representing an enumeration and its values
* GIEnumInfo:
*
* A GIEnumInfo represents an enumeration, and a GIValueInfo represents
* a value in the enumeration.
* A `GIEnumInfo` represents an enumeration.
*
* The GIEnumInfo contains a set of values and a type.
* The `GIEnumInfo` contains a set of values (each a
* [class@GIRepository.ValueInfo]) and a type.
*
* The GIValueInfo is fetched by calling gi_enum_info_get_value() on
* a GIEnumInfo.
* The [class@GIRepository.ValueInfo] for a value is fetched by calling
* [method@GIRepository.EnumInfo.get_value] on a `GIEnumInfo`.
*
* Since: 2.80
*/
/**
@ -53,6 +53,7 @@
* Obtain the number of values this enumeration contains.
*
* Returns: the number of enumeration values
* Since: 2.80
*/
guint
gi_enum_info_get_n_values (GIEnumInfo *info)
@ -75,8 +76,8 @@ gi_enum_info_get_n_values (GIEnumInfo *info)
* Obtain the string form of the quark for the error domain associated with
* this enum, if any.
*
* Returns: (transfer none): the string form of the error domain associated
* with this enum, or %NULL.
* Returns: (transfer none) (nullable): the string form of the error domain
* associated with this enum, or `NULL`.
* Since: 2.80
*/
const gchar *
@ -103,8 +104,9 @@ gi_enum_info_get_error_domain (GIEnumInfo *info)
*
* Obtain a value for this enumeration.
*
* Returns: (transfer full): the enumeration value or %NULL if type tag is wrong,
* free the struct with gi_base_info_unref() when done.
* Returns: (transfer full): the enumeration value, free the struct with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIValueInfo *
gi_enum_info_get_value (GIEnumInfo *info,
@ -154,8 +156,8 @@ gi_enum_info_get_n_methods (GIEnumInfo *info)
*
* Obtain an enum type method at index @n.
*
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): the [class@GIRepository.FunctionInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
@ -193,6 +195,7 @@ gi_enum_info_get_method (GIEnumInfo *info,
* may not match the sign of the type used by the C compiler.
*
* Returns: the storage type for the enumeration
* Since: 2.80
*/
GITypeTag
gi_enum_info_get_storage_type (GIEnumInfo *info)
@ -217,15 +220,27 @@ gi_enum_info_class_init (gpointer g_class,
info_class->info_type = GI_INFO_TYPE_ENUM;
}
/**
* GIValueInfo:
*
* A `GIValueInfo` represents a value in an enumeration.
*
* The `GIValueInfo` is fetched by calling
* [method@GIRepository.EnumInfo.get_value] on a [class@GIRepository.EnumInfo].
*
* Since: 2.80
*/
/**
* gi_value_info_get_value:
* @info: a #GIValueInfo
*
* Obtain the enumeration value of the #GIValueInfo.
* Obtain the enumeration value of the `GIValueInfo`.
*
* Returns: the enumeration value. This will always be representable
* as a 32-bit signed or unsigned value. The use of gint64 as the
* as a 32-bit signed or unsigned value. The use of `gint64` as the
* return type is to allow both.
* Since: 2.80
*/
gint64
gi_value_info_get_value (GIValueInfo *info)

12
girepository/gienuminfo.h
View File

@ -33,20 +33,24 @@
G_BEGIN_DECLS
/**
* GI_IS_ENUM_INFO
* GI_IS_ENUM_INFO:
* @info: an info structure
*
* Checks if @info is a #GIEnumInfo.
* Checks if @info is a [class@GIRepository.EnumInfo].
*
* Since: 2.80
*/
#define GI_IS_ENUM_INFO(info) \
((gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_ENUM) || \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FLAGS))
/**
* GI_IS_VALUE_INFO
* GI_IS_VALUE_INFO:
* @info: an info structure
*
* Checks if @info is a #GIValueInfo.
* Checks if @info is a [class@GIRepository.ValueInfo].
*
* Since: 2.80
*/
#define GI_IS_VALUE_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_VALUE)

5
girepository/gifieldinfo.c
View File

@ -141,6 +141,7 @@ gi_field_info_get_offset (GIFieldInfo *info)
*
* Returns: (transfer full): the [type@GIRepository.TypeInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GITypeInfo *
gi_field_info_get_type_info (GIFieldInfo *info)
@ -181,7 +182,7 @@ gi_field_info_get_type_info (GIFieldInfo *info)
* composite type like a nested structure or union even if that is actually
* readable.
*
* Returns: true if reading the field succeeded, false otherwise
* Returns: `TRUE` if reading the field succeeded, `FALSE` otherwise
* Since: 2.80
*/
gboolean
@ -378,7 +379,7 @@ gi_field_info_get_field (GIFieldInfo *field_info,
* management would by required. A field with a type such as `char *` must be
* set with a setter function.
*
* Returns: true if writing the field succeeded, false otherwise
* Returns: `TRUE` if writing the field succeeded, `FALSE` otherwise
* Since: 2.80
*/
gboolean

91
girepository/gifunctioninfo.c
View File

@ -35,17 +35,17 @@
#include "gifunctioninfo.h"
/**
* SECTION:gifunctioninfo
* @title: GIFunctionInfo
* @short_description: Struct representing a function
* GIFunctionInfo:
*
* GIFunctionInfo represents a function, method or constructor.
* `GIFunctionInfo` represents a function, method or constructor.
*
* To find out what kind of entity a #GIFunctionInfo represents, call
* gi_function_info_get_flags().
* To find out what kind of entity a `GIFunctionInfo` represents, call
* [method@GIRepository.FunctionInfo.get_flags].
*
* See also #GICallableInfo for information on how to retreive arguments and
* other metadata.
* See also [class@GIRepository.CallableInfo] for information on how to retrieve
* arguments and other metadata.
*
* Since: 2.80
*/
GIFunctionInfo *
@ -77,11 +77,13 @@ gi_base_info_find_method (GIBaseInfo *base,
* gi_function_info_get_symbol:
* @info: a #GIFunctionInfo
*
* Obtain the symbol of the function. The symbol is the name of the
* exported function, suitable to be used as an argument to
* g_module_symbol().
* Obtain the symbol of the function.
*
* The symbol is the name of the exported function, suitable to be used as an
* argument to [method@GModule.Module.symbol].
*
* Returns: the symbol
* Since: 2.80
*/
const gchar *
gi_function_info_get_symbol (GIFunctionInfo *info)
@ -102,9 +104,10 @@ gi_function_info_get_symbol (GIFunctionInfo *info)
* gi_function_info_get_flags:
* @info: a #GIFunctionInfo
*
* Obtain the #GIFunctionInfoFlags for the @info.
* Obtain the [type@GIRepository.FunctionInfoFlags] for the @info.
*
* Returns: the flags
* Since: 2.80
*/
GIFunctionInfoFlags
gi_function_info_get_flags (GIFunctionInfo *info)
@ -147,13 +150,15 @@ gi_function_info_get_flags (GIFunctionInfo *info)
* gi_function_info_get_property:
* @info: a #GIFunctionInfo
*
* Obtain the property associated with this #GIFunctionInfo.
* Only #GIFunctionInfo with the flag %GI_FUNCTION_IS_GETTER or
* %GI_FUNCTION_IS_SETTER have a property set. For other cases,
* %NULL will be returned.
* Obtain the property associated with this `GIFunctionInfo`.
*
* Returns: (transfer full): the property or %NULL if not set. Free it with
* gi_base_info_unref() when done.
* Only `GIFunctionInfo`s with the flag `GI_FUNCTION_IS_GETTER` or
* `GI_FUNCTION_IS_SETTER` have a property set. For other cases,
* `NULL` will be returned.
*
* Returns: (transfer full) (nullable): The property or `NULL` if not set. Free
* it with [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIPropertyInfo *
gi_function_info_get_property (GIFunctionInfo *info)
@ -187,12 +192,14 @@ gi_function_info_get_property (GIFunctionInfo *info)
* gi_function_info_get_vfunc:
* @info: a #GIFunctionInfo
*
* Obtain the virtual function associated with this #GIFunctionInfo.
* Only #GIFunctionInfo with the flag %GI_FUNCTION_WRAPS_VFUNC has
* a virtual function set. For other cases, %NULL will be returned.
* Obtain the virtual function associated with this `GIFunctionInfo`.
*
* Returns: (transfer full): the virtual function or %NULL if not set.
* Free it by calling gi_base_info_unref() when done.
* Only `GIFunctionInfo`s with the flag `GI_FUNCTION_WRAPS_VFUNC` have
* a virtual function set. For other cases, `NULL` will be returned.
*
* Returns: (transfer full) (nullable): The virtual function or `NULL` if not
* set. Free it by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_function_info_get_vfunc (GIFunctionInfo *info)
@ -214,9 +221,10 @@ gi_function_info_get_vfunc (GIFunctionInfo *info)
/**
* gi_invoke_error_quark:
*
* TODO
* Get the error quark which represents [type@GIRepository.InvokeError].
*
* Returns: TODO
* Returns: error quark
* Since: 2.80
*/
GQuark
gi_invoke_error_quark (void)
@ -230,27 +238,30 @@ gi_invoke_error_quark (void)
/**
* gi_function_info_invoke: (skip)
* @info: a #GIFunctionInfo describing the function to invoke
* @in_args: (array length=n_in_args): an array of #GIArgument<!-- -->s, one for each in
* parameter of @info. If there are no in parameter, @in_args
* can be %NULL
* @in_args: (array length=n_in_args) (nullable): An array of
* [type@GIRepository.Argument]s, one for each ‘in’ parameter of @info. If
* there are no ‘in’ parameters, @in_args can be `NULL`.
* @n_in_args: the length of the @in_args array
* @out_args: (array length=n_out_args): an array of #GIArgument<!-- -->s, one for each out
* parameter of @info. If there are no out parameters, @out_args
* may be %NULL
* @out_args: (array length=n_out_args) (nullable): An array of
* [type@GIRepository.Argument]s, one for each ‘out’ parameter of @info. If
* there are no ‘out’ parameters, @out_args may be `NULL`.
* @n_out_args: the length of the @out_args array
* @return_value: return location for the return value of the
* function.
* @error: return location for detailed error information, or %NULL
* @return_value: (out caller-allocates) (not optional): return location for the
* return value of the function.
* @error: return location for detailed error information, or `NULL`
*
* Invokes the function described in @info with the given
* arguments. Note that inout parameters must appear in both
* argument lists. This function uses dlsym() to obtain a pointer
* to the function, so the library or shared object containing the
* described function must either be linked to the caller, or must
* have been g_module_symbol()<!-- -->ed before calling this function.
* arguments.
*
* Returns: %TRUE if the function has been invoked, %FALSE if an
* Note that ‘inout’ parameters must appear in both argument lists. This
* function uses [`dlsym()`](man:dlsym(3)) to obtain a pointer to the function,
* so the library or shared object containing the described function must either
* be linked to the caller, or must have been loaded with
* [method@GModule.Module.symbol] before calling this function.
*
* Returns: `TRUE` if the function has been invoked, `FALSE` if an
* error occurred.
* Since: 2.80
*/
gboolean
gi_function_info_invoke (GIFunctionInfo *info,

25
girepository/gifunctioninfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_FUNCTION_INFO
* GI_IS_FUNCTION_INFO:
* @info: an info structure
*
* Checks if @info is a #GIFunctionInfo.
* Checks if @info is a [class@GIRepository.FunctionInfo].
*
* Since: 2.80
*/
#define GI_IS_FUNCTION_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FUNCTION)
@ -57,7 +59,9 @@ GIVFuncInfo * gi_function_info_get_vfunc (GIFunctionInfo *info);
/**
* GI_INVOKE_ERROR:
*
* TODO
* Type quark function for [enum@GIRepository.InvokeError].
*
* Since: 2.80
*/
#define GI_INVOKE_ERROR (gi_invoke_error_quark ())
@ -66,16 +70,17 @@ GQuark gi_invoke_error_quark (void);
/**
* GIInvokeError:
* @GI_INVOKE_ERROR_FAILED: invokation failed, unknown error.
* @GI_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn't be found in any of the
* @GI_INVOKE_ERROR_FAILED: invocation failed, unknown error.
* @GI_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn’t be found in any of the
* libraries associated with the typelib of the function.
* @GI_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn't match
* the expected arguments for the functions type signature.
* @GI_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn’t match
* the expected arguments for the function’s type signature.
*
* An error occuring while invoking a function via
* gi_function_info_invoke().
* An error occurring while invoking a function via
* [method@GIRepository.FunctionInfo.invoke].
*
* Since: 2.80
*/
typedef enum
{
GI_INVOKE_ERROR_FAILED,

99
girepository/giinterfaceinfo.c
View File

@ -33,14 +33,14 @@
#include "giinterfaceinfo.h"
/**
* SECTION:giinterfaceinfo
* @title: GIInterfaceInfo
* @short_description: Struct representing a GInterface
* GIInterfaceInfo:
*
* GIInterfaceInfo represents a #GInterface type.
* `GIInterfaceInfo` represents a `GInterface` type.
*
* A GInterface has methods, fields, properties, signals, interfaces, constants,
* virtual functions and prerequisites.
* A `GInterface` has methods, fields, properties, signals,
* interfaces, constants, virtual functions and prerequisites.
*
* Since: 2.80
*/
/**
@ -48,10 +48,12 @@
* @info: a #GIInterfaceInfo
*
* Obtain the number of prerequisites for this interface type.
* A prerequisites is another interface that needs to be implemented for
* interface, similar to an base class for GObjects.
*
* A prerequisite is another interface that needs to be implemented for
* interface, similar to a base class for [class@GObject.Object]s.
*
* Returns: number of prerequisites
* Since: 2.80
*/
guint
gi_interface_info_get_n_prerequisites (GIInterfaceInfo *info)
@ -70,12 +72,13 @@ gi_interface_info_get_n_prerequisites (GIInterfaceInfo *info)
/**
* gi_interface_info_get_prerequisite:
* @info: a #GIInterfaceInfo
* @n: index of prerequisites to get
* @n: index of prerequisite to get
*
* Obtain an interface type prerequisites index @n.
* Obtain an interface type’s prerequisite at index @n.
*
* Returns: (transfer full): the prerequisites as a #GIBaseInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The prerequisite as a [class@GIRepository.BaseInfo].
* Free the struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIBaseInfo *
gi_interface_info_get_prerequisite (GIInterfaceInfo *info,
@ -101,6 +104,7 @@ gi_interface_info_get_prerequisite (GIInterfaceInfo *info,
* Obtain the number of properties that this interface type has.
*
* Returns: number of properties
* Since: 2.80
*/
guint
gi_interface_info_get_n_properties (GIInterfaceInfo *info)
@ -123,8 +127,9 @@ gi_interface_info_get_n_properties (GIInterfaceInfo *info)
*
* Obtain an interface type property at index @n.
*
* Returns: (transfer full): the #GIPropertyInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.PropertyInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIPropertyInfo *
gi_interface_info_get_property (GIInterfaceInfo *info,
@ -156,6 +161,7 @@ gi_interface_info_get_property (GIInterfaceInfo *info,
* Obtain the number of methods that this interface type has.
*
* Returns: number of methods
* Since: 2.80
*/
guint
gi_interface_info_get_n_methods (GIInterfaceInfo *info)
@ -178,8 +184,9 @@ gi_interface_info_get_n_methods (GIInterfaceInfo *info)
*
* Obtain an interface type method at index @n.
*
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_interface_info_get_method (GIInterfaceInfo *info,
@ -210,11 +217,14 @@ gi_interface_info_get_method (GIInterfaceInfo *info,
* @info: a #GIInterfaceInfo
* @name: name of method to obtain
*
* Obtain a method of the interface type given a @name. %NULL will be
* returned if there's no method available with that name.
* Obtain a method of the interface type given a @name.
*
* Returns: (transfer full): the #GIFunctionInfo or %NULL if none found.
* Free the struct by calling gi_base_info_unref() when done.
* `NULL` will be returned if there’s no method available with that name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo] or
* `NULL` if none found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_interface_info_find_method (GIInterfaceInfo *info,
@ -239,6 +249,7 @@ gi_interface_info_find_method (GIInterfaceInfo *info,
* Obtain the number of signals that this interface type has.
*
* Returns: number of signals
* Since: 2.80
*/
guint
gi_interface_info_get_n_signals (GIInterfaceInfo *info)
@ -261,8 +272,9 @@ gi_interface_info_get_n_signals (GIInterfaceInfo *info)
*
* Obtain an interface type signal at index @n.
*
* Returns: (transfer full): the #GISignalInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.SignalInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GISignalInfo *
gi_interface_info_get_signal (GIInterfaceInfo *info,
@ -292,12 +304,15 @@ gi_interface_info_get_signal (GIInterfaceInfo *info,
/**
* gi_interface_info_find_signal:
* @info: a #GIInterfaceInfo
* @name: Name of signal
* @name: name of signal to find
*
* TODO
* Obtain a signal of the interface type given a @name.
*
* Returns: (transfer full): Info for the signal with name @name in @info, or
* %NULL on failure.
* `NULL` will be returned if there’s no signal available with that name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.SignalInfo] or
* `NULL` if none found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GISignalInfo *
@ -329,6 +344,7 @@ gi_interface_info_find_signal (GIInterfaceInfo *info,
* Obtain the number of virtual functions that this interface type has.
*
* Returns: number of virtual functions
* Since: 2.80
*/
guint
gi_interface_info_get_n_vfuncs (GIInterfaceInfo *info)
@ -351,8 +367,9 @@ gi_interface_info_get_n_vfuncs (GIInterfaceInfo *info)
*
* Obtain an interface type virtual function at index @n.
*
* Returns: (transfer full): the #GIVFuncInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): the [class@GIRepository.VFuncInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_interface_info_get_vfunc (GIInterfaceInfo *info,
@ -385,11 +402,15 @@ gi_interface_info_get_vfunc (GIInterfaceInfo *info,
* @info: a #GIInterfaceInfo
* @name: The name of a virtual function to find.
*
* Locate a virtual function slot with name @name. See the documentation
* for gi_object_info_find_vfunc() for more information on virtuals.
* Locate a virtual function slot with name @name.
*
* Returns: (transfer full): the #GIVFuncInfo, or %NULL. Free it with
* gi_base_info_unref() when done.
* See the documentation for [method@GIRepository.ObjectInfo.find_vfunc] for
* more information on virtuals.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.VFuncInfo], or
* `NULL` if none found. Free it with [method@GIRepository.BaseInfo.unref]
* when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_interface_info_find_vfunc (GIInterfaceInfo *info,
@ -422,6 +443,7 @@ gi_interface_info_find_vfunc (GIInterfaceInfo *info,
* Obtain the number of constants that this interface type has.
*
* Returns: number of constants
* Since: 2.80
*/
guint
gi_interface_info_get_n_constants (GIInterfaceInfo *info)
@ -444,8 +466,9 @@ gi_interface_info_get_n_constants (GIInterfaceInfo *info)
*
* Obtain an interface type constant at index @n.
*
* Returns: (transfer full): the #GIConstantInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.ConstantInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIConstantInfo *
gi_interface_info_get_constant (GIInterfaceInfo *info,
@ -478,10 +501,12 @@ gi_interface_info_get_constant (GIInterfaceInfo *info,
* gi_interface_info_get_iface_struct:
* @info: a #GIInterfaceInfo
*
* Returns the layout C structure associated with this #GInterface.
* Returns the layout C structure associated with this `GInterface`.
*
* Returns: (transfer full): the #GIStructInfo or %NULL. Free it with
* gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.StructInfo] or
* `NULL` if unknown. Free it with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
*/
GIStructInfo *
gi_interface_info_get_iface_struct (GIInterfaceInfo *info)

6
girepository/giinterfaceinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_INTERFACE_INFO
* GI_IS_INTERFACE_INFO:
* @info: an info structure
*
* Checks if @info is a #GIInterfaceInfo.
* Checks if @info is a [class@GIRepository.InterfaceInfo].
*
* Since: 2.80
*/
#define GI_IS_INTERFACE_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_INTERFACE)

56
girepository/ginvoke.c
View File

@ -33,10 +33,15 @@
/**
* value_to_ffi_type:
* @gvalue: TODO
* @value: TODO
* @gvalue: (transfer none): a [type@GObject.Value] to convert
* @value: (out caller-allocates): return location for the ffi data
*
* TODO
* Convert @gvalue to a format suitable for passing to ffi.
*
* @value is only valid as long as @gvalue is alive.
*
* Returns: pointer to the `ffi_type` associated with @value
* Since: 2.80
*/
static ffi_type *
value_to_ffi_type (const GValue *gvalue, gpointer *value)
@ -101,11 +106,18 @@ value_to_ffi_type (const GValue *gvalue, gpointer *value)
/**
* g_value_to_ffi_return_type:
* @gvalue: TODO
* @ffi_value: TODO
* @value: TODO
* @gvalue: (transfer none): a [type@GObject.Value] to convert
* @ffi_value: (transfer none): a [type@GIRepository.Argument] containing the
* data to use
* @value: (out caller-allocates): return location for the ffi data
*
* TODO
* Convert @ffi_value to a format suitable for passing to ffi, using the type
* data from @gvalue.
*
* @value is only valid as long as @gvalue and @ffi_value are alive.
*
* Returns: pointer to the `ffi_type` associated with @value
* Since: 2.80
*/
static ffi_type *
g_value_to_ffi_return_type (const GValue *gvalue,
@ -172,10 +184,15 @@ g_value_to_ffi_return_type (const GValue *gvalue,
/**
* g_value_from_ffi_value:
* @gvalue: TODO
* @value: TODO
* @gvalue: (inout): a [type@GObject.Value] to set
* @value: (transfer none): ffi data to convert
*
* TODO
* Convert @value to a [type@GObject.Value] according to the type already set
* on @gvalue.
*
* @gvalue is valid even after @value is finalised.
*
* Since: 2.80
*/
static void
g_value_from_ffi_value (GValue *gvalue,
@ -236,14 +253,19 @@ g_value_from_ffi_value (GValue *gvalue,
/**
* gi_cclosure_marshal_generic: (skip)
* @closure: TODO
* @return_gvalue: TODO
* @n_param_values: TODO
* @param_values: TODO
* @invocation_hint: TODO
* @marshal_data: TODO
* @closure: a [type@GObject.Closure]
* @return_gvalue: (optional) (out caller-allocates): return location for the
* return value from the closure, or `NULL` to ignore
* @n_param_values: number of param values
* @param_values: (array length=n_param_values): values to pass to the closure
* parameters
* @invocation_hint: invocation hint
* @marshal_data: marshal data
*
* TODO
* A generic C closure marshal function using ffi and
* [type@GIRepository.Argument].
*
* Since: 2.80
*/
void
gi_cclosure_marshal_generic (GClosure *closure,

278
girepository/giobjectinfo.c
View File

@ -33,20 +33,20 @@
#include "giobjectinfo.h"
/**
* SECTION:giobjectinfo
* @title: GIObjectInfo
* @short_description: Struct representing a classed type
* GIObjectInfo:
*
* GIObjectInfo represents a classed type.
* `GIObjectInfo` represents a classed type.
*
* Classed types in GType inherit from #GTypeInstance; the most common
* type is #GObject.
* Classed types in [type@GObject.Type] inherit from
* [type@GObject.TypeInstance]; the most common type is [class@GObject.Object].
*
* A GIObjectInfo doesn't represent a specific instance of a classed type,
* instead this represent the object type (eg class).
* A `GIObjectInfo` doesn’t represent a specific instance of a classed type,
* instead this represent the object type (i.e. the class).
*
* A GIObjectInfo has methods, fields, properties, signals, interfaces,
* A `GIObjectInfo` has methods, fields, properties, signals, interfaces,
* constants and virtual functions.
*
* Since: 2.80
*/
/**
@ -56,7 +56,8 @@
*
* Obtain the offset of the specified field.
*
* Returns: field offset in bytes
* Returns: field offset, in bytes
* Since: 2.80
*/
static gint32
gi_object_info_get_field_offset (GIObjectInfo *info,
@ -88,8 +89,9 @@ gi_object_info_get_field_offset (GIObjectInfo *info,
*
* Obtain the parent of the object type.
*
* Returns: (transfer full) (nullable): the #GIObjectInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The `GIObjectInfo`. Free the struct by
* calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIObjectInfo *
gi_object_info_get_parent (GIObjectInfo *info)
@ -113,10 +115,11 @@ gi_object_info_get_parent (GIObjectInfo *info)
* gi_object_info_get_abstract:
* @info: a #GIObjectInfo
*
* Obtain if the object type is an abstract type, eg if it cannot be
* instantiated
* Obtain if the object type is an abstract type, i.e. if it cannot be
* instantiated.
*
* Returns: %TRUE if the object type is abstract
* Returns: `TRUE` if the object type is abstract
* Since: 2.80
*/
gboolean
gi_object_info_get_abstract (GIObjectInfo *info)
@ -137,10 +140,9 @@ gi_object_info_get_abstract (GIObjectInfo *info)
* @info: a #GIObjectInfo
*
* Checks whether the object type is a final type, i.e. if it cannot
* be derived
*
* Returns: %TRUE if the object type is final
* be derived.
*
* Returns: `TRUE` if the object type is final
* Since: 2.80
*/
gboolean
@ -162,9 +164,12 @@ gi_object_info_get_final (GIObjectInfo *info)
* @info: a #GIObjectInfo
*
* Obtain if the object type is of a fundamental type which is not
* G_TYPE_OBJECT. This is mostly for supporting GstMiniObject.
* `G_TYPE_OBJECT`.
*
* Returns: %TRUE if the object type is a fundamental type
* This is mostly for supporting `GstMiniObject`.
*
* Returns: `TRUE` if the object type is a fundamental type
* Since: 2.80
*/
gboolean
gi_object_info_get_fundamental (GIObjectInfo *info)
@ -184,9 +189,10 @@ gi_object_info_get_fundamental (GIObjectInfo *info)
* gi_object_info_get_type_name:
* @info: a #GIObjectInfo
*
* Obtain the name of the objects class/type.
* Obtain the name of the object’s class/type.
*
* Returns: name of the objects type
* Returns: name of the object’s type
* Since: 2.80
*/
const gchar *
gi_object_info_get_type_name (GIObjectInfo *info)
@ -206,10 +212,11 @@ gi_object_info_get_type_name (GIObjectInfo *info)
* gi_object_info_get_type_init_function_name:
* @info: a #GIObjectInfo
*
* Obtain the function which when called will return the GType
* function for which this object type is registered.
* Obtain the name of the function which, when called, will return the
* [type@GObject.Type] for this object type.
*
* Returns: the type init function
* Returns: the type init function name
* Since: 2.80
*/
const gchar *
gi_object_info_get_type_init_function_name (GIObjectInfo *info)
@ -232,6 +239,7 @@ gi_object_info_get_type_init_function_name (GIObjectInfo *info)
* Obtain the number of interfaces that this object type has.
*
* Returns: number of interfaces
* Since: 2.80
*/
guint
gi_object_info_get_n_interfaces (GIObjectInfo *info)
@ -254,8 +262,9 @@ gi_object_info_get_n_interfaces (GIObjectInfo *info)
*
* Obtain an object type interface at index @n.
*
* Returns: (transfer full): the #GIInterfaceInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.InterfaceInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIInterfaceInfo *
gi_object_info_get_interface (GIObjectInfo *info,
@ -280,6 +289,7 @@ gi_object_info_get_interface (GIObjectInfo *info,
* Obtain the number of fields that this object type has.
*
* Returns: number of fields
* Since: 2.80
*/
guint
gi_object_info_get_n_fields (GIObjectInfo *info)
@ -302,8 +312,9 @@ gi_object_info_get_n_fields (GIObjectInfo *info)
*
* Obtain an object type field at index @n.
*
* Returns: (transfer full): the #GIFieldInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFieldInfo *
gi_object_info_get_field (GIObjectInfo *info,
@ -327,6 +338,7 @@ gi_object_info_get_field (GIObjectInfo *info,
* Obtain the number of properties that this object type has.
*
* Returns: number of properties
* Since: 2.80
*/
guint
gi_object_info_get_n_properties (GIObjectInfo *info)
@ -348,8 +360,9 @@ gi_object_info_get_n_properties (GIObjectInfo *info)
*
* Obtain an object type property at index @n.
*
* Returns: (transfer full): the #GIPropertyInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.PropertyInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIPropertyInfo *
gi_object_info_get_property (GIObjectInfo *info,
@ -383,6 +396,7 @@ gi_object_info_get_property (GIObjectInfo *info,
* Obtain the number of methods that this object type has.
*
* Returns: number of methods
* Since: 2.80
*/
guint
gi_object_info_get_n_methods (GIObjectInfo *info)
@ -405,8 +419,9 @@ gi_object_info_get_n_methods (GIObjectInfo *info)
*
* Obtain an object type method at index @n.
*
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_object_info_get_method (GIObjectInfo *info,
@ -440,11 +455,14 @@ gi_object_info_get_method (GIObjectInfo *info,
* @info: a #GIObjectInfo
* @name: name of method to obtain
*
* Obtain a method of the object type given a @name. %NULL will be
* returned if there's no method available with that name.
* Obtain a method of the object type given a @name.
*
* Returns: (transfer full) (nullable): the #GIFunctionInfo. Free the struct by calling
* gi_base_info_unref() when done.
* `NULL` will be returned if there’s no method available with that name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* or `NULL` if no method could be found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_object_info_find_method (GIObjectInfo *info,
@ -474,17 +492,22 @@ gi_object_info_find_method (GIObjectInfo *info,
* gi_object_info_find_method_using_interfaces:
* @info: a #GIObjectInfo
* @name: name of method to obtain
* @implementor: (out) (transfer full): The implementor of the interface
* @implementor: (out) (transfer full) (optional) (nullable): The implementor of
* the interface, or `NULL` to ignore. If no method is found, this will return
* `NULL`.
*
* Obtain a method of the object given a @name, searching both the
* object @info and any interfaces it implements. %NULL will be
* returned if there's no method available with that name.
* object @info and any interfaces it implements.
*
* `NULL` will be returned if there’s no method available with that name.
*
* Note that this function does *not* search parent classes; you will have
* to chain up if that's desired.
* to chain up if that’s desired.
*
* Returns: (transfer full) (nullable): the #GIFunctionInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* or `NULL` if none was found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_object_info_find_method_using_interfaces (GIObjectInfo *info,
@ -534,6 +557,7 @@ gi_object_info_find_method_using_interfaces (GIObjectInfo *info,
* Obtain the number of signals that this object type has.
*
* Returns: number of signals
* Since: 2.80
*/
guint
gi_object_info_get_n_signals (GIObjectInfo *info)
@ -556,8 +580,9 @@ gi_object_info_get_n_signals (GIObjectInfo *info)
*
* Obtain an object type signal at index @n.
*
* Returns: (transfer full): the #GISignalInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.SignalInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GISignalInfo *
gi_object_info_get_signal (GIObjectInfo *info,
@ -589,11 +614,16 @@ gi_object_info_get_signal (GIObjectInfo *info,
/**
* gi_object_info_find_signal:
* @info: a #GIObjectInfo
* @name: Name of signal
* @name: name of signal
*
* TODO
* Obtain a signal of the object type given a @name.
*
* Returns: (transfer full) (nullable): Info for the signal with name @name in @info, or %NULL on failure.
* `NULL` will be returned if there’s no signal available with that name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.SignalInfo],
* or `NULL` if no signal could be found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GISignalInfo *
gi_object_info_find_signal (GIObjectInfo *info,
@ -625,6 +655,7 @@ gi_object_info_find_signal (GIObjectInfo *info,
* Obtain the number of virtual functions that this object type has.
*
* Returns: number of virtual functions
* Since: 2.80
*/
guint
gi_object_info_get_n_vfuncs (GIObjectInfo *info)
@ -647,8 +678,9 @@ gi_object_info_get_n_vfuncs (GIObjectInfo *info)
*
* Obtain an object type virtual function at index @n.
*
* Returns: (transfer full): the #GIVFuncInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.VFuncInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_object_info_get_vfunc (GIObjectInfo *info,
@ -681,18 +713,22 @@ gi_object_info_get_vfunc (GIObjectInfo *info,
/**
* gi_object_info_find_vfunc:
* @info: a #GIObjectInfo
* @name: The name of a virtual function to find.
* @name: the name of a virtual function to find.
*
* Locate a virtual function slot with name @name. Note that the namespace
* for virtuals is distinct from that of methods; there may or may not be
* a concrete method associated for a virtual. If there is one, it may
* be retrieved using gi_vfunc_info_get_invoker(), otherwise %NULL will be
* returned.
* See the documentation for gi_vfunc_info_get_invoker() for more
* information on invoking virtuals.
* Locate a virtual function slot with name @name.
*
* Returns: (transfer full) (nullable): the #GIVFuncInfo, or %NULL. Free it with
* gi_base_info_unref() when done.
* Note that the namespace for virtuals is distinct from that of methods; there
* may or may not be a concrete method associated for a virtual. If there is
* one, it may be retrieved using [method@GIRepository.VFuncInfo.get_invoker],
* otherwise that method will return `NULL`.
*
* See the documentation for [method@GIRepository.VFuncInfo.get_invoker] for
* more information on invoking virtuals.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.VFuncInfo], or
* `NULL` if none is found. Free it with [method@GIRepository.BaseInfo.unref]
* when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_object_info_find_vfunc (GIObjectInfo *info,
@ -724,20 +760,27 @@ gi_object_info_find_vfunc (GIObjectInfo *info,
* gi_object_info_find_vfunc_using_interfaces:
* @info: a #GIObjectInfo
* @name: name of vfunc to obtain
* @implementor: (out) (transfer full): The implementor of the interface
* @implementor: (out) (transfer full) (optional) (nullable): The implementor of
* the interface, or `NULL` to ignore. If no vfunc is found, this will return
* `NULL`.
*
* Locate a virtual function slot with name @name, searching both the object
* @info and any interfaces it implements. Note that the namespace for
* virtuals is distinct from that of methods; there may or may not be a
* concrete method associated for a virtual. If there is one, it may be
* retrieved using gi_vfunc_info_get_invoker(), otherwise %NULL will be
* returned.
* @info and any interfaces it implements.
*
* `NULL` will be returned if there’s no vfunc available with that name.
*
* Note that the namespace for virtuals is distinct from that of methods; there
* may or may not be a concrete method associated for a virtual. If there is
* one, it may be retrieved using [method@GIRepository.VFuncInfo.get_invoker],
* otherwise that method will return `NULL`.
*
* Note that this function does *not* search parent classes; you will have
* to chain up if that's desired.
* to chain up if that’s desired.
*
* Returns: (transfer full) (nullable): the #GIVFuncInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.VFuncInfo],
* or `NULL` if none was found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIVFuncInfo *
gi_object_info_find_vfunc_using_interfaces (GIObjectInfo *info,
@ -787,6 +830,7 @@ gi_object_info_find_vfunc_using_interfaces (GIObjectInfo *info,
* Obtain the number of constants that this object type has.
*
* Returns: number of constants
* Since: 2.80
*/
guint
gi_object_info_get_n_constants (GIObjectInfo *info)
@ -809,8 +853,9 @@ gi_object_info_get_n_constants (GIObjectInfo *info)
*
* Obtain an object type constant at index @n.
*
* Returns: (transfer full): the #GIConstantInfo. Free the struct by calling
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.ConstantInfo]. Free the
* struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIConstantInfo *
gi_object_info_get_constant (GIObjectInfo *info,
@ -845,11 +890,13 @@ gi_object_info_get_constant (GIObjectInfo *info,
* gi_object_info_get_class_struct:
* @info: a #GIObjectInfo
*
* Every #GObject has two structures; an instance structure and a class
* structure. This function returns the metadata for the class structure.
* Every [class@GObject.Object] has two structures; an instance structure and a
* class structure. This function returns the metadata for the class structure.
*
* Returns: (transfer full) (nullable): the #GIStructInfo or %NULL. Free with
* gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.StructInfo] or
* `NULL` if it’s unknown. Free with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
*/
GIStructInfo *
gi_object_info_get_class_struct (GIObjectInfo *info)
@ -908,11 +955,16 @@ _get_func(GIObjectInfo *info,
* @info: a #GIObjectInfo
*
* Obtain the symbol name of the function that should be called to ref this
* object type. It's mainly used fundamental types. The type signature for
* the symbol is %GIObjectInfoRefFunction, to fetch the function pointer
* see gi_object_info_get_ref_function_name().
* object type.
*
* Returns: (nullable): the symbol or %NULL
* It’s mainly used for fundamental types. The type signature for
* the symbol is [type@GIRepository.ObjectInfoRefFunction]. To fetch the
* function pointer see
* [method@GIRepository.ObjectInfo.get_ref_function_pointer].
*
* Returns: (nullable): the symbol, or `NULL` if the object type has no ref
* function
* Since: 2.80
*/
const char *
gi_object_info_get_ref_function_name (GIObjectInfo *info)
@ -937,10 +989,13 @@ gi_object_info_get_ref_function_name (GIObjectInfo *info)
*
* Obtain a pointer to a function which can be used to
* increase the reference count an instance of this object type.
*
* This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type.
*
* Returns: (nullable): the function pointer or %NULL
* Returns: (nullable): the function pointer, or `NULL` if the object type has
* no ref function
* Since: 2.80
*/
GIObjectInfoRefFunction
gi_object_info_get_ref_function_pointer (GIObjectInfo *info)
@ -956,11 +1011,15 @@ gi_object_info_get_ref_function_pointer (GIObjectInfo *info)
* @info: a #GIObjectInfo
*
* Obtain the symbol name of the function that should be called to unref this
* object type. It's mainly used fundamental types. The type signature for
* the symbol is %GIObjectInfoUnrefFunction, to fetch the function pointer
* see gi_object_info_get_unref_function_name().
* object type.
*
* Returns: (nullable): the symbol or %NULL
* It’s mainly used for fundamental types. The type signature for the symbol is
* [type@GIRepository.ObjectInfoUnrefFunction]. To fetch the function pointer
* see [method@GIRepository.ObjectInfo.get_unref_function_pointer].
*
* Returns: (nullable): the symbol, or `NULL` if the object type has no unref
* function
* Since: 2.80
*/
const char *
gi_object_info_get_unref_function_name (GIObjectInfo *info)
@ -985,10 +1044,13 @@ gi_object_info_get_unref_function_name (GIObjectInfo *info)
*
* Obtain a pointer to a function which can be used to
* decrease the reference count an instance of this object type.
*
* This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type.
*
* Returns: (nullable): the function pointer or %NULL
* Returns: (nullable): the function pointer, or `NULL` if the object type has
* no unref function
* Since: 2.80
*/
GIObjectInfoUnrefFunction
gi_object_info_get_unref_function_pointer (GIObjectInfo *info)
@ -1003,13 +1065,16 @@ gi_object_info_get_unref_function_pointer (GIObjectInfo *info)
* gi_object_info_get_set_value_function_name:
* @info: a #GIObjectInfo
*
* Obtain the symbol name of the function that should be called to convert
* set a GValue giving an object instance pointer of this object type.
* I's mainly used fundamental types. The type signature for the symbol
* is %GIObjectInfoSetValueFunction, to fetch the function pointer
* see gi_object_info_get_set_value_function_name().
* Obtain the symbol name of the function that should be called to set a
* [type@GObject.Value], given an object instance pointer of this object type.
*
* Returns: (nullable): the symbol or %NULL
* It’s mainly used for fundamental types. The type signature for the symbol
* is [type@GIRepository.ObjectInfoSetValueFunction]. To fetch the function
* pointer see [method@GIRepository.ObjectInfo.get_set_value_function_pointer].
*
* Returns: (nullable): the symbol, or `NULL` if the object type has no
* set-value function
* Since: 2.80
*/
const char *
gi_object_info_get_set_value_function_name (GIObjectInfo *info)
@ -1032,12 +1097,15 @@ gi_object_info_get_set_value_function_name (GIObjectInfo *info)
* gi_object_info_get_set_value_function_pointer: (skip)
* @info: a #GIObjectInfo
*
* Obtain a pointer to a function which can be used to
* set a GValue given an instance of this object type.
* Obtain a pointer to a function which can be used to set a
* [type@GObject.Value], given an instance of this object type.
*
* This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type.
*
* Returns: (nullable): the function pointer or %NULL
* Returns: (nullable): the function pointer, or `NULL` if the object type has
* no set-value function
* Since: 2.80
*/
GIObjectInfoSetValueFunction
gi_object_info_get_set_value_function_pointer (GIObjectInfo *info)
@ -1053,12 +1121,15 @@ gi_object_info_get_set_value_function_pointer (GIObjectInfo *info)
* @info: a #GIObjectInfo
*
* Obtain the symbol name of the function that should be called to convert
* an object instance pointer of this object type to a GValue.
* I's mainly used fundamental types. The type signature for the symbol
* is %GIObjectInfoGetValueFunction, to fetch the function pointer
* see gi_object_info_get_get_value_function_name().
* an object instance pointer of this object type to a [type@GObject.Value].
*
* Returns: (nullable): the symbol or %NULL
* It’s mainly used for fundamental types. The type signature for the symbol
* is [type@GIRepository.ObjectInfoGetValueFunction]. To fetch the function
* pointer see [method@GIRepository.ObjectInfo.get_get_value_function_pointer].
*
* Returns: (nullable): the symbol, or `NULL` if the object type has no
* get-value function
* Since: 2.80
*/
const char *
gi_object_info_get_get_value_function_name (GIObjectInfo *info)
@ -1081,12 +1152,15 @@ gi_object_info_get_get_value_function_name (GIObjectInfo *info)
* gi_object_info_get_get_value_function_pointer: (skip)
* @info: a #GIObjectInfo
*
* Obtain a pointer to a function which can be used to
* extract an instance of this object type out of a GValue.
* Obtain a pointer to a function which can be used to extract an instance of
* this object type out of a [type@GObject.Value].
*
* This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type.
*
* Returns: (nullable): the function pointer or %NULL
* Returns: (nullable): the function pointer, or `NULL` if the object type has
* no get-value function
* Since: 2.80
*/
GIObjectInfoGetValueFunction
gi_object_info_get_get_value_function_pointer (GIObjectInfo *info)

20
girepository/giobjectinfo.h
View File

@ -39,41 +39,49 @@ G_BEGIN_DECLS
* Increases the reference count of an object instance.
*
* Returns: (transfer full): the object instance
* Since: 2.80
*/
typedef void * (*GIObjectInfoRefFunction) (void *object);
/**
* GIObjectInfoUnrefFunction: (skip)
* @object: object instance pointer
* @object: (transfer full): object instance pointer
*
* Decreases the reference count of an object instance.
*
* Since: 2.80
*/
typedef void (*GIObjectInfoUnrefFunction) (void *object);
/**
* GIObjectInfoSetValueFunction: (skip)
* @value: a #GValue
* @value: a [type@GObject.Value]
* @object: object instance pointer
*
* Update @value and attach the object instance pointer @object to it.
*
* Since: 2.80
*/
typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
/**
* GIObjectInfoGetValueFunction: (skip)
* @value: a #GValue
* @value: a [type@GObject.Value]
*
* Extract an object instance out of @value
* Extract an object instance out of @value.
*
* Returns: (transfer full): the object instance
* Since: 2.80
*/
typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value);
/**
* GI_IS_OBJECT_INFO
* GI_IS_OBJECT_INFO:
* @info: an info structure
*
* Checks if @info is a #GIObjectInfo.
* Checks if @info is a [class@GIRepository.ObjectInfo].
*
* Since: 2.80
*/
#define GI_IS_OBJECT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_OBJECT)

49
girepository/gipropertyinfo.c
View File

@ -33,23 +33,27 @@
#include "gipropertyinfo.h"
/**
* SECTION:gipropertyinfo
* @title: GIPropertyInfo
* @short_description: Struct representing a property
* GIPropertyInfo:
*
* GIPropertyInfo represents a property in a #GObject.
* `GIPropertyInfo` represents a property in a [class@GObject.Object].
*
* A property belongs to either a #GIObjectInfo or a #GIInterfaceInfo.
* A property belongs to either a [class@GIRepository.ObjectInfo] or a
* [class@GIRepository.InterfaceInfo].
*
* Since: 2.80
*/
/**
* gi_property_info_get_flags:
* @info: a #GIPropertyInfo
*
* Obtain the flags for this property info. See #GParamFlags for
* more information about possible flag values.
* Obtain the flags for this property info.
*
* See [type@GObject.ParamFlags] for more information about possible flag
* values.
*
* Returns: the flags
* Since: 2.80
*/
GParamFlags
gi_property_info_get_flags (GIPropertyInfo *info)
@ -86,8 +90,9 @@ gi_property_info_get_flags (GIPropertyInfo *info)
*
* Obtain the type information for the property @info.
*
* Returns: (transfer full): the #GITypeInfo, free it with
* gi_base_info_unref() when done.
* Returns: (transfer full): The [class@GIRepository.TypeInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GITypeInfo *
gi_property_info_get_type_info (GIPropertyInfo *info)
@ -106,10 +111,12 @@ gi_property_info_get_type_info (GIPropertyInfo *info)
* gi_property_info_get_ownership_transfer:
* @info: a #GIPropertyInfo
*
* Obtain the ownership transfer for this property. See #GITransfer for more
* information about transfer values.
* Obtain the ownership transfer for this property.
*
* See [type@GIRepository.Transfer] for more information about transfer values.
*
* Returns: the transfer
* Since: 2.80
*/
GITransfer
gi_property_info_get_ownership_transfer (GIPropertyInfo *info)
@ -134,13 +141,14 @@ gi_property_info_get_ownership_transfer (GIPropertyInfo *info)
* gi_property_info_get_setter:
* @info: a #GIPropertyInfo
*
* Obtains the setter function associated with this #GIPropertyInfo.
* Obtains the setter function associated with this `GIPropertyInfo`.
*
* The setter is only available for %G_PARAM_WRITABLE properties that
* are also not %G_PARAM_CONSTRUCT_ONLY.
* The setter is only available for `G_PARAM_WRITABLE` properties that
* are also not `G_PARAM_CONSTRUCT_ONLY`.
*
* Returns: (transfer full) (nullable): the function info or %NULL if not set.
* Free it with gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The function info, or `NULL` if not set.
* Free it with [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_property_info_get_setter (GIPropertyInfo *info)
@ -174,12 +182,13 @@ gi_property_info_get_setter (GIPropertyInfo *info)
* gi_property_info_get_getter:
* @info: a #GIPropertyInfo
*
* Obtains the getter function associated with this #GIPropertyInfo.
* Obtains the getter function associated with this `GIPropertyInfo`.
*
* The setter is only available for %G_PARAM_READABLE properties.
* The setter is only available for `G_PARAM_READABLE` properties.
*
* Returns: (transfer full) (nullable): the function info or %NULL if not set.
* Free it with gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The function info, or `NULL` if not set.
* Free it with [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_property_info_get_getter (GIPropertyInfo *info)

6
girepository/gipropertyinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_PROPERTY_INFO
* GI_IS_PROPERTY_INFO:
* @info: an info structure
*
* Checks if @info is a #GIPropertyInfo.
* Checks if @info is a [class@GIRepository.PropertyInfo].
*
* Since: 2.80
*/
#define GI_IS_PROPERTY_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_PROPERTY)

54
girepository/giregisteredtypeinfo.c
View File

@ -35,20 +35,22 @@
#include "giregisteredtypeinfo.h"
/**
* SECTION:giregisteredtypeinfo
* @title: GIRegisteredTypeInfo
* @short_description: Struct representing a struct with a GType
* GIRegisteredTypeInfo:
*
* GIRegisteredTypeInfo represents an entity with a GType associated.
* `GIRegisteredTypeInfo` represents an entity with a [type@GObject.Type]
* associated.
*
* Could be either a #GIEnumInfo, #GIInterfaceInfo, #GIObjectInfo,
* #GIStructInfo or a #GIUnionInfo.
* Could be either a [class@GIRepository.EnumInfo],
* [class@GIRepository.InterfaceInfo], [class@GIRepository.ObjectInfo],
* [class@GIRepository.StructInfo] or a [class@GIRepository.UnionInfo].
*
* A registered type info struct has a name and a type function.
*
* To get the name call gi_registered_type_info_get_type_name().
* Most users want to call gi_registered_type_info_get_g_type() and don't worry
* about the rest of the details.
* To get the name call [method@GIRepository.RegisteredTypeInfo.get_type_name].
* Most users want to call [method@GIRepository.RegisteredTypeInfo.get_g_type]
* and don’t worry about the rest of the details.
*
* Since: 2.80
*/
/**
@ -56,9 +58,12 @@
* @info: a #GIRegisteredTypeInfo
*
* Obtain the type name of the struct within the GObject type system.
* This type can be passed to g_type_name() to get a #GType.
*
* Returns: the type name
* This type can be passed to [func@GObject.type_name] to get a
* [type@GObject.Type].
*
* Returns: (nullable): the type name, or `NULL` if unknown
* Since: 2.80
*/
const gchar *
gi_registered_type_info_get_type_name (GIRegisteredTypeInfo *info)
@ -81,13 +86,16 @@ gi_registered_type_info_get_type_name (GIRegisteredTypeInfo *info)
* gi_registered_type_info_get_type_init_function_name:
* @info: a #GIRegisteredTypeInfo
*
* Obtain the type init function for @info. The type init function is the
* function which will register the GType within the GObject type system.
* Usually this is not called by langauge bindings or applications, use
* gi_registered_type_info_get_g_type() directly instead.
* Obtain the type init function for @info.
*
* Returns: the symbol name of the type init function, suitable for
* passing into g_module_symbol().
* The type init function is the function which will register the
* [type@GObject.Type] within the GObject type system. Usually this is not
* called by language bindings or applications — use
* [method@GIRepository.RegisteredTypeInfo.get_g_type] directly instead.
*
* Returns: (nullable): the symbol name of the type init function, suitable for
* passing into [method@GModule.Module.symbol], or `NULL` if unknown
* Since: 2.80
*/
const gchar *
gi_registered_type_info_get_type_init_function_name (GIRegisteredTypeInfo *info)
@ -110,12 +118,14 @@ gi_registered_type_info_get_type_init_function_name (GIRegisteredTypeInfo *info)
* gi_registered_type_info_get_g_type:
* @info: a #GIRegisteredTypeInfo
*
* Obtain the #GType for this registered type or G_TYPE_NONE which a special meaning.
* It means that either there is no type information associated with this @info or
* that the shared library which provides the type_init function for this
* @info cannot be called.
* Obtain the [type@GObject.Type] for this registered type.
*
* Returns: the #GType.
* If there is no type information associated with @info, or the shared library
* which provides the `type_init` function for @info cannot be called, then
* `G_TYPE_NONE` is returned.
*
* Returns: the [type@GObject.Type], or `G_TYPE_NONE` if unknown
* Since: 2.80
*/
GType
gi_registered_type_info_get_g_type (GIRegisteredTypeInfo *info)

7
girepository/giregisteredtypeinfo.h
View File

@ -34,10 +34,13 @@
G_BEGIN_DECLS
/**
* GI_IS_REGISTERED_TYPE_INFO
* GI_IS_REGISTERED_TYPE_INFO:
* @info: an info structure
*
* Checks if @info is a #GIRegisteredTypeInfo or derived from it.
* Checks if @info is a [class@GIRepository.RegisteredTypeInfo] or derived from
* it.
*
* Since: 2.80
*/
#define GI_IS_REGISTERED_TYPE_INFO(info) \
((gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_BOXED) || \

312
girepository/girepository.c
View File

@ -37,26 +37,26 @@
#include "girepository-private.h"
/**
* SECTION:girepository
* @short_description: GObject Introspection repository manager
* @include: girepository.h
* GIRepository:
*
* #GIRepository is used to manage repositories of namespaces. Namespaces
* are represented on disk by type libraries (.typelib files).
* `GIRepository` is used to manage repositories of namespaces. Namespaces
* are represented on disk by type libraries (`.typelib` files).
*
* ### Discovery of type libraries
*
* #GIRepository will typically look for a `girepository-1.0` directory
* under the library directory used when compiling gobject-introspection.
* `GIRepository` will typically look for a `girepository-1.0` directory
* under the library directory used when compiling gobject-introspection. On a
* standard Linux system this will end up being `/usr/lib/girepository-1.0`.
*
* It is possible to control the search paths programmatically, using
* gi_repository_prepend_search_path(). It is also possible to modify
* the search paths by using the `GI_TYPELIB_PATH` environment variable.
* [func@GIRepository.Repository.prepend_search_path]. It is also possible to
* modify the search paths by using the `GI_TYPELIB_PATH` environment variable.
* The environment variable takes precedence over the default search path
* and the gi_repository_prepend_search_path() calls.
* and the [func@GIRepository.Repository.prepend_search_path] calls.
*
* Since: 2.80
*/
static GIRepository *default_repository = NULL;
static GSList *typelib_search_path = NULL;
@ -237,6 +237,8 @@ init_globals (void)
* Prepends @directory to the typelib search path.
*
* See also: gi_repository_get_search_path().
*
* Since: 2.80
*/
void
gi_repository_prepend_search_path (const char *directory)
@ -248,11 +250,15 @@ gi_repository_prepend_search_path (const char *directory)
/**
* gi_repository_get_search_path:
*
* Returns the current search path #GIRepository will use when loading
* typelib files. The list is internal to #GIRepository and should not
* be freed, nor should its string elements.
* Returns the current search path [class@GIRepository.Repository] will use when
* loading typelib files.
*
* Returns: (element-type filename) (transfer none): #GSList of strings
* The list is internal to [class@GIRepository.Repository] and should not be
* freed, nor should its string elements.
*
* Returns: (element-type filename) (transfer none): list of search paths, most
* important first
* Since: 2.80
*/
GSList *
gi_repository_get_search_path (void)
@ -454,7 +460,7 @@ register_internal (GIRepository *repository,
/**
* gi_repository_get_immediate_dependencies:
* @repository: (nullable): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace of interest
*
@ -462,14 +468,14 @@ register_internal (GIRepository *repository,
* Returned strings are of the form `namespace-version`.
*
* Note: @namespace_ must have already been loaded using a function
* such as gi_repository_require() before calling this function.
* such as [method@GIRepository.Repository.require] before calling this
* function.
*
* To get the transitive closure of dependencies for @namespace_, use
* gi_repository_get_dependencies().
*
* Returns: (transfer full): Zero-terminated string array of immediate versioned
* dependencies
* [method@GIRepository.Repository.get_dependencies].
*
* Returns: (transfer full) (array zero-terminated=1): `NULL`-terminated string
* array of immediate versioned dependencies
* Since: 2.80
*/
char **
@ -537,7 +543,7 @@ get_typelib_dependencies_transitive (GIRepository *repository,
/**
* gi_repository_get_dependencies:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace of interest
*
@ -547,13 +553,15 @@ get_typelib_dependencies_transitive (GIRepository *repository,
* The strings are of the form `namespace-version`.
*
* Note: @namespace_ must have already been loaded using a function
* such as gi_repository_require() before calling this function.
* such as [method@GIRepository.Repository.require] before calling this
* function.
*
* To get only the immediate dependencies for @namespace_, use
* gi_repository_get_immediate_dependencies().
* [method@GIRepository.Repository.get_immediate_dependencies].
*
* Returns: (transfer full) (array zero-terminated=1): all versioned
* dependencies
* Returns: (transfer full) (array zero-terminated=1): `NULL`-terminated string
* array of all versioned dependencies
* Since: 2.80
*/
char **
gi_repository_get_dependencies (GIRepository *repository,
@ -599,13 +607,16 @@ gi_repository_get_dependencies (GIRepository *repository,
/**
* gi_repository_load_typelib:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @typelib: TODO
* @flags: TODO
* @error: TODO
* @typelib: the typelib to load
* @flags: flags affecting the loading operation
* @error: return location for a [type@GLib.Error], or `NULL`
*
* TODO
* Load the given @typelib into the repository.
*
* Returns: namespace of the loaded typelib
* Since: 2.80
*/
const char *
gi_repository_load_typelib (GIRepository *repository,
@ -645,19 +656,22 @@ gi_repository_load_typelib (GIRepository *repository,
/**
* gi_repository_is_registered:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace of interest
* @version: (allow-none): Required version, may be %NULL for latest
* @version: (nullable): Required version, may be `NULL` for latest
*
* Check whether a particular namespace (and optionally, a specific
* version thereof) is currently loaded. This function is likely to
* only be useful in unusual circumstances; in order to act upon
* metadata in the namespace, you should call gi_repository_require()
* instead which will ensure the namespace is loaded, and return as
* quickly as this function will if it has already been loaded.
* version thereof) is currently loaded.
*
* Returns: %TRUE if namespace-version is loaded, %FALSE otherwise
* This function is likely to only be useful in unusual circumstances; in order
* to act upon metadata in the namespace, you should call
* [method@GIRepository.Repository.require] instead which will ensure the
* namespace is loaded, and return as quickly as this function will if it has
* already been loaded.
*
* Returns: `TRUE` if namespace-version is loaded, `FALSE` otherwise
* Since: 2.80
*/
gboolean
gi_repository_is_registered (GIRepository *repository,
@ -671,18 +685,20 @@ gi_repository_is_registered (GIRepository *repository,
/**
* gi_repository_get_default:
*
* Returns the singleton process-global default #GIRepository. It is
* not currently supported to have multiple repositories in a
* Returns the singleton process-global default #GIRepository.
*
* It is not currently supported to have multiple repositories in a
* particular process, but this function is provided in the unlikely
* eventuality that it would become possible, and as a convenience for
* higher level language bindings to conform to the GObject method
* call conventions.
*
* All methods on #GIRepository also accept %NULL as an instance
* All methods on #GIRepository also accept `NULL` as an instance
* parameter to mean this default repository, which is usually more
* convenient for C.
*
* Returns: (transfer none): The global singleton #GIRepository
* Returns: (transfer none): The global singleton [class@GIRepository.Repository]
* Since: 2.80
*/
GIRepository *
gi_repository_get_default (void)
@ -693,12 +709,12 @@ gi_repository_get_default (void)
/**
* gi_repository_new:
*
* Create a new (non-singleton) #GIRepository.
* Create a new (non-singleton) [class@GIRepository.Repository].
*
* Most callers should use gi_repository_get_default() instead, as a singleton
* repository is more useful in most situations.
* Most callers should use [func@GIRepository.Repository.get_default] instead,
* as a singleton repository is more useful in most situations.
*
* Returns: (transfer full): a new #GIRepository
* Returns: (transfer full): a new [class@GIRepository.Repository]
* Since: 2.80
*/
GIRepository *
@ -709,15 +725,17 @@ gi_repository_new (void)
/**
* gi_repository_get_n_infos:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the number of metadata entries in
* given namespace @namespace_. The namespace must have
* already been loaded before calling this function.
* given namespace @namespace_.
*
* The namespace must have already been loaded before calling this function.
*
* Returns: number of metadata entries
* Since: 2.80
*/
guint
gi_repository_get_n_infos (GIRepository *repository,
@ -741,18 +759,21 @@ gi_repository_get_n_infos (GIRepository *repository,
/**
* gi_repository_get_info:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace to inspect
* @idx: 0-based offset into namespace metadata for entry
*
* This function returns a particular metadata entry in the
* given namespace @namespace_. The namespace must have
* already been loaded before calling this function.
* See gi_repository_get_n_infos() to find the maximum number of
* entries.
* given namespace @namespace_.
*
* Returns: (transfer full): #GIBaseInfo containing metadata
* The namespace must have already been loaded before calling this function.
* See [method@GIRepository.Repository.get_n_infos] to find the maximum number
* of entries.
*
* Returns: (transfer full) (nullable): [class@GIRepository.BaseInfo] containing
* metadata, or `NULL` if @idx was too high
* Since: 2.80
*/
GIBaseInfo *
gi_repository_get_info (GIRepository *repository,
@ -813,18 +834,21 @@ find_by_gtype (GHashTable *table, FindByGTypeData *data, gboolean check_prefix)
/**
* gi_repository_find_by_gtype:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @gtype: GType to search for
* @gtype: [type@GObject.Type] to search for
*
* Searches all loaded namespaces for a particular #GType. Note that
* in order to locate the metadata, the namespace corresponding to
* Searches all loaded namespaces for a particular [type@GObject.Type].
*
* Note that in order to locate the metadata, the namespace corresponding to
* the type must first have been loaded. There is currently no
* mechanism for determining the namespace which corresponds to an
* arbitrary GType - thus, this function will operate most reliably
* when you know the GType to originate from be from a loaded namespace.
* arbitrary [type@GObject.Type] — thus, this function will operate most
* reliably when you know the [type@GObject.Type] is from a loaded namespace.
*
* Returns: (transfer full): #GIBaseInfo representing metadata about @type, or %NULL
* Returns: (transfer full) (nullable): [class@GIRepository.BaseInfo]
* representing metadata about @type, or `NULL` if none found
* Since: 2.80
*/
GIBaseInfo *
gi_repository_find_by_gtype (GIRepository *repository,
@ -891,17 +915,20 @@ gi_repository_find_by_gtype (GIRepository *repository,
/**
* gi_repository_find_by_name:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace which will be searched
* @name: Entry name to find
*
* Searches for a particular entry in a namespace. Before calling
* this function for a particular namespace, you must call
* gi_repository_require() once to load the namespace, or otherwise
* Searches for a particular entry in a namespace.
*
* Before calling this function for a particular namespace, you must call
* [method@GIRepository.Repository.require] to load the namespace, or otherwise
* ensure the namespace has already been loaded.
*
* Returns: (transfer full): #GIBaseInfo representing metadata about @name, or %NULL
* Returns: (transfer full) (nullable): [class@GIRepository.BaseInfo]
* representing metadata about @name, or `NULL` if none found
* Since: 2.80
*/
GIBaseInfo *
gi_repository_find_by_name (GIRepository *repository,
@ -951,17 +978,19 @@ find_by_error_domain_foreach (gpointer key,
/**
* gi_repository_find_by_error_domain:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @domain: a #GError domain
* @domain: a [type@GLib.Error] domain
*
* Searches for the enum type corresponding to the given #GError
* domain. Before calling this function for a particular namespace,
* you must call gi_repository_require() once to load the namespace, or
* otherwise ensure the namespace has already been loaded.
* Searches for the enum type corresponding to the given [type@GLib.Error]
* domain.
*
* Returns: (transfer full): #GIEnumInfo representing metadata about @domain's
* enum type, or %NULL
* Before calling this function for a particular namespace, you must call
* [method@GIRepository.Repository.require] to load the namespace, or otherwise
* ensure the namespace has already been loaded.
*
* Returns: (transfer full) (nullable): [class@GIRepository.EnumInfo]
* representing metadata about @domain’s enum type, or `NULL` if none found
* Since: 2.80
*/
GIEnumInfo *
@ -1004,22 +1033,24 @@ gi_repository_find_by_error_domain (GIRepository *repository,
/**
* gi_repository_get_object_gtype_interfaces:
* @repository: (nullable): a #GIRepository, or %NULL for the default repository
* @gtype: a #GType whose fundamental type is G_TYPE_OBJECT
* @repository: (nullable): a #GIRepository, or `NULL` for the default repository
* @gtype: a [type@GObject.Type] whose fundamental type is `G_TYPE_OBJECT`
* @n_interfaces_out: (out): Number of interfaces
* @interfaces_out: (out) (transfer none) (array length=n_interfaces_out): Interfaces for @gtype
*
* Look up the implemented interfaces for @gtype. This function
* cannot fail per se; but for a totally "unknown" #GType, it may
* return 0 implemented interfaces.
* Look up the implemented interfaces for @gtype.
*
* This function cannot fail per se; but for a totally ‘unknown’
* [type@GObject.Type], it may return 0 implemented interfaces.
*
* The semantics of this function are designed for a dynamic binding,
* where in certain cases (such as a function which returns an
* interface which may have "hidden" implementation classes), not all
* interface which may have ‘hidden’ implementation classes), not all
* data may be statically known, and will have to be determined from
* the #GType of the object. An example is g_file_new_for_path()
* returning a concrete class of #GLocalFile, which is a #GType we
* see at runtime, but not statically.
* the [type@GObject.Type] of the object. An example is
* [func@Gio.File.new_for_path] returning a concrete class of
* `GLocalFile`, which is a [type@GObject.Type] we see at runtime, but
* not statically.
*
* Since: 2.80
*/
@ -1093,12 +1124,14 @@ collect_namespaces (gpointer key,
/**
* gi_repository_get_loaded_namespaces:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
*
* Return the list of currently loaded namespaces.
*
* Returns: (element-type utf8) (transfer full): List of namespaces
* Returns: (element-type utf8) (transfer full) (array zero-terminated=1): `NULL`-terminated
* list of namespaces
* Since: 2.80
*/
gchar **
gi_repository_get_loaded_namespaces (GIRepository *repository)
@ -1123,7 +1156,7 @@ gi_repository_get_loaded_namespaces (GIRepository *repository)
/**
* gi_repository_get_version:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace to inspect
*
@ -1131,9 +1164,11 @@ gi_repository_get_loaded_namespaces (GIRepository *repository)
* namespace @namespace_.
*
* Note: The namespace must have already been loaded using a function
* such as gi_repository_require() before calling this function.
* such as [method@GIRepository.Repository.require] before calling this
* function.
*
* Returns: Loaded version
* Since: 2.80
*/
const gchar *
gi_repository_get_version (GIRepository *repository,
@ -1156,20 +1191,23 @@ gi_repository_get_version (GIRepository *repository,
/**
* gi_repository_get_shared_library:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns a comma-separated list of paths to the
* shared C libraries associated with the given namespace @namespace_.
*
* There may be no shared library path associated, in which case this
* function will return %NULL.
* function will return `NULL`.
*
* Note: The namespace must have already been loaded using a function
* such as gi_repository_require() before calling this function.
* such as [method@GIRepository.Repository.require] before calling this
* function.
*
* Returns: (nullable): Comma-separated list of paths to shared libraries,
* or %NULL if none are associated
* or `NULL` if none are associated
* Since: 2.80
*/
const gchar *
gi_repository_get_shared_library (GIRepository *repository,
@ -1195,18 +1233,22 @@ gi_repository_get_shared_library (GIRepository *repository,
/**
* gi_repository_get_c_prefix:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the "C prefix", or the C level namespace
* associated with the given introspection namespace. Each C symbol
* starts with this prefix, as well each #GType in the library.
* This function returns the ‘C prefix’, or the C level namespace
* associated with the given introspection namespace.
*
* Each C symbol starts with this prefix, as well each [type@GObject.Type] in
* the library.
*
* Note: The namespace must have already been loaded using a function
* such as gi_repository_require() before calling this function.
* such as [method@GIRepository.Repository.require] before calling this
* function.
*
* Returns: C namespace prefix, or %NULL if none associated
* Returns: (nullable): C namespace prefix, or `NULL` if none associated
* Since: 2.80
*/
const gchar *
gi_repository_get_c_prefix (GIRepository *repository,
@ -1232,18 +1274,20 @@ gi_repository_get_c_prefix (GIRepository *repository,
/**
* gi_repository_get_typelib_path:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: GI namespace to use, e.g. "Gtk"
* @namespace_: GI namespace to use, e.g. `Gtk`
*
* If namespace @namespace_ is loaded, return the full path to the
* .typelib file it was loaded from. If the typelib for
* namespace @namespace_ was included in a shared library, return
* the special string "&lt;builtin&gt;".
* .typelib file it was loaded from.
*
* Returns: Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded
* If the typelib for namespace @namespace_ was included in a shared library,
* return the special string `<builtin>`.
*
* Returns: (type filename) (nullable): Filesystem path (or `<builtin>`) if
* successful, `NULL` if namespace is not loaded
* Since: 2.80
*/
const gchar *
gi_repository_get_typelib_path (GIRepository *repository,
const gchar *namespace)
@ -1511,14 +1555,15 @@ find_namespace_latest (const gchar *namespace,
/**
* gi_repository_enumerate_versions:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: GI namespace, e.g. "Gtk"
* @namespace_: GI namespace, e.g. `Gtk`
*
* Obtain an unordered list of versions (either currently loaded or
* available) for @namespace_ in this @repository.
*
* Returns: (element-type utf8) (transfer full): the array of versions.
* Since: 2.80
*/
GList *
gi_repository_enumerate_versions (GIRepository *repository,
@ -1670,20 +1715,23 @@ require_internal (GIRepository *repository,
/**
* gi_repository_require:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @namespace_: GI namespace to use, e.g. "Gtk"
* @version: (allow-none): Version of namespace, may be %NULL for latest
* @flags: Set of %GIRepositoryLoadFlags, may be 0
* @error: a #GError.
* @namespace_: GI namespace to use, e.g. `Gtk`
* @version: (nullable): Version of namespace, may be `NULL` for latest
* @flags: Set of [flags@GIRepository.RepositoryLoadFlags], may be 0
* @error: a [type@GLib.Error].
*
* Force the namespace @namespace_ to be loaded if it isn’t already.
*
* Force the namespace @namespace_ to be loaded if it isn't already.
* If @namespace_ is not loaded, this function will search for a
* ".typelib" file using the repository search path. In addition, a
* `.typelib` file using the repository search path. In addition, a
* version @version of namespace may be specified. If @version is
* not specified, the latest will be used.
*
* Returns: (transfer none): a pointer to the #GITypelib if successful, %NULL otherwise
* Returns: (transfer none): a pointer to the [type@GIRepository.Typelib] if
* successful, `NULL` otherwise
* Since: 2.80
*/
GITypelib *
gi_repository_require (GIRepository *repository,
@ -1703,21 +1751,25 @@ gi_repository_require (GIRepository *repository,
/**
* gi_repository_require_private:
* @repository: (allow-none): A #GIRepository or %NULL for the singleton
* @repository: (nullable): A #GIRepository, or `NULL` for the singleton
* process-global default #GIRepository
* @typelib_dir: Private directory where to find the requested typelib
* @namespace_: GI namespace to use, e.g. "Gtk"
* @version: (allow-none): Version of namespace, may be %NULL for latest
* @flags: Set of %GIRepositoryLoadFlags, may be 0
* @error: a #GError.
* @typelib_dir: (type filename): Private directory where to find the requested
* typelib
* @namespace_: GI namespace to use, e.g. `Gtk`
* @version: (nullable): Version of namespace, may be `NULL` for latest
* @flags: Set of [flags@GIRepository.RepositoryLoadFlags], may be 0
* @error: a [type@GLib.Error].
*
* Force the namespace @namespace_ to be loaded if it isn’t already.
*
* Force the namespace @namespace_ to be loaded if it isn't already.
* If @namespace_ is not loaded, this function will search for a
* ".typelib" file within the private directory only. In addition, a
* `.typelib` file within the private directory only. In addition, a
* version @version of namespace should be specified. If @version is
* not specified, the latest will be used.
*
* Returns: (transfer none): a pointer to the #GITypelib if successful, %NULL otherwise
* Returns: (transfer none): a pointer to the [type@GIRepository.Typelib] if
* successful, `NULL` otherwise
* Since: 2.80
*/
GITypelib *
gi_repository_require_private (GIRepository *repository,
@ -1763,11 +1815,13 @@ static const GOptionEntry introspection_args[] = {
/**
* gi_repository_get_option_group:
*
* Obtain the option group for girepository, it's used
* by the dumper and for programs that wants to provide
* introspection information
* Obtain the option group for girepository.
*
* It’s used by the dumper and for programs that want to provide introspection
* information
*
* Returns: (transfer full): the option group
* Since: 2.80
*/
GOptionGroup *
gi_repository_get_option_group (void)
@ -1795,6 +1849,7 @@ gi_repository_error_quark (void)
* Obtain a string representation of @type
*
* Returns: the string
* Since: 2.80
*/
const gchar*
gi_type_tag_to_string (GITypeTag type)
@ -1857,6 +1912,7 @@ gi_type_tag_to_string (GITypeTag type)
* Obtain a string representation of @type
*
* Returns: the string
* Since: 2.80
*/
const gchar*
gi_info_type_to_string (GIInfoType type)

23
girepository/girepository.h
View File

@ -61,12 +61,6 @@ G_BEGIN_DECLS
#define GI_IS_REPOSITORY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GI_TYPE_REPOSITORY))
#define GI_REPOSITORY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GI_TYPE_REPOSITORY, GIRepositoryClass))
/**
* GIRepository:
*
* The GIRepository structure contains private data and should only be
* accessed using the provided API.
*/
typedef struct _GIRepository GIRepository;
typedef struct _GIRepositoryClass GIRepositoryClass;
typedef struct _GIRepositoryPrivate GIRepositoryPrivate;
@ -89,6 +83,8 @@ struct _GIRepositoryClass
* @GI_REPOSITORY_LOAD_FLAG_LAZY: Lazily load the typelib.
*
* Flags that control how a typelib is loaded.
*
* Since: 2.80
*/
typedef enum
{
@ -217,8 +213,10 @@ gboolean gi_repository_dump (const char *input_filename,
* @GI_REPOSITORY_ERROR_LIBRARY_NOT_FOUND: the library used by the typelib
* could not be found.
*
* An error code used with #GI_REPOSITORY_ERROR in a #GError returned
* from a #GIRepository routine.
* An error code used with `GI_REPOSITORY_ERROR` in a [type@GLib.Error]
* returned from a [class@GIRepository.Repository] routine.
*
* Since: 2.80
*/
typedef enum
{
@ -231,9 +229,12 @@ typedef enum
/**
* GI_REPOSITORY_ERROR:
*
* Error domain for #GIRepository. Errors in this domain will be from the
* #GIRepositoryError enumeration. See #GError for more information on
* error domains.
* Error domain for [class@GIRepository.Repository].
*
* Errors in this domain will be from the [enum@GIRepository.Error] enumeration.
* See [type@GLib.Error] for more information on error domains.
*
* Since: 2.80
*/
#define GI_REPOSITORY_ERROR (gi_repository_error_quark ())

95
girepository/girffi.c
View File

@ -35,14 +35,6 @@
#include "girepository.h"
#include "girepository-private.h"
/**
* SECTION:girffi
* @short_description: TODO
* @title: girffi
*
* TODO
*/
static ffi_type *
gi_type_tag_get_ffi_type_internal (GITypeTag tag,
gboolean is_pointer,
@ -115,12 +107,14 @@ gi_type_tag_get_ffi_type_internal (GITypeTag tag,
/**
* gi_type_tag_get_ffi_type:
* @type_tag: A #GITypeTag
* @is_pointer: Whether or not this is a pointer type
* @type_tag: a #GITypeTag
* @is_pointer: whether this is a pointer type
*
* TODO
* Get the `ffi_type` corresponding to @type_tag.
*
* Returns: A #ffi_type corresponding to the platform default C ABI for @tag and @is_pointer.
* Returns: (transfer none): an `ffi_type` corresponding to the platform default
* C ABI for @tag and @is_pointer.
* Since: 2.80
*/
ffi_type *
gi_type_tag_get_ffi_type (GITypeTag type_tag,
@ -131,11 +125,13 @@ gi_type_tag_get_ffi_type (GITypeTag type_tag,
/**
* gi_type_info_get_ffi_type:
* @info: A #GITypeInfo
* @info: a #GITypeInfo
*
* TODO
* Get the `ffi_type` corresponding to @info.
*
* Returns: A #ffi_type corresponding to the platform default C ABI for @info.
* Returns: (transfer none): a `ffi_type` corresponding to the platform default
* C ABI for @info.
* Since: 2.80
*/
ffi_type *
gi_type_info_get_ffi_type (GITypeInfo *info)
@ -164,12 +160,14 @@ gi_type_info_get_ffi_type (GITypeInfo *info)
/**
* gi_callable_info_get_ffi_arg_types:
* @callable_info: a callable info from a typelib
* @n_args_p: (out): The number of arguments
* @n_args_p: (out) (optional): the number of arguments returned
*
* TODO
* Get the `ffi_type`s for the arguments of @callable_info.
*
* Returns: an array of ffi_type*. The array itself
* should be freed using g_free() after use.
* Returns: (transfer container) (array length=n_args_p): an array of
* `ffi_type*`. The array itself should be freed using [func@GLib.free] after
* use.
* Since: 2.80
*/
static ffi_type **
gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
@ -233,10 +231,11 @@ gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
* gi_callable_info_get_ffi_return_type:
* @callable_info: a callable info from a typelib
*
* Fetches the ffi_type for a corresponding return value of
* a #GICallableInfo
* Fetches the `ffi_type` for a corresponding return value of
* a [class@GIRepository.CallableInfo].
*
* Returns: the ffi_type for the return value
* Returns: (transfer none): the `ffi_type` for the return value
* Since: 2.80
*/
static ffi_type *
gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
@ -256,18 +255,19 @@ gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
/**
* gi_function_info_prep_invoker:
* @info: A #GIFunctionInfo
* @invoker: Output invoker structure
* @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError
*
* Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to
* @info with the platform's default ABI.
* @info with the platform’s default ABI.
*
* A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure
* inside the binding's function mapping.
* by a language binding could contain a [type@GIRepository.FunctionInvoker]
* structure inside the binding’s function mapping.
*
* Returns: %TRUE on success, %FALSE otherwise with @error set.
* Returns: `TRUE` on success, `FALSE` otherwise with @error set.
* Since: 2.80
*/
gboolean
gi_function_info_prep_invoker (GIFunctionInfo *info,
@ -300,18 +300,19 @@ gi_function_info_prep_invoker (GIFunctionInfo *info,
* gi_function_invoker_new_for_address:
* @addr: The address
* @info: A #GICallableInfo
* @invoker: Output invoker structure
* @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError
*
* Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to
* @info with the platform's default ABI.
* @info with the platform’s default ABI.
*
* A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure
* inside the binding's function mapping.
* by a language binding could contain a [type@GIRepository.FunctionInvoker]
* structure inside the binding’s function mapping.
*
* Returns: %TRUE on success, %FALSE otherwise with @error set.
* Returns: `TRUE` on success, `FALSE` otherwise with @error set.
* Since: 2.80
*/
gboolean
gi_function_invoker_new_for_address (gpointer addr,
@ -336,11 +337,14 @@ gi_function_invoker_new_for_address (gpointer addr,
/**
* gi_function_invoker_destroy:
* @invoker: A #GIFunctionInvoker
* @invoker: (transfer none): A #GIFunctionInvoker
*
* Release all resources allocated for the internals of @invoker; callers
* are responsible for freeing any resources allocated for the structure
* Release all resources allocated for the internals of @invoker.
*
* Callers are responsible for freeing any resources allocated for the structure
* itself however.
*
* Since: 2.80
*/
void
gi_function_invoker_destroy (GIFunctionInvoker *invoker)
@ -357,14 +361,16 @@ typedef struct {
/**
* gi_callable_info_create_closure:
* @callable_info: a callable info from a typelib
* @cif: a ffi_cif structure
* @cif: a `ffi_cif` structure
* @callback: the ffi callback
* @user_data: data to be passed into the callback
*
* Prepares a callback for ffi invocation.
*
* Returns: the ffi_closure or NULL on error. The return value
* should be freed by calling gi_callable_info_destroy_closure().
* Returns: (transfer full) (nullable): the `ffi_closure`, or `NULL` on error.
* The return value should be freed by calling
* [method@GIRepository.CallableInfo.destroy_closure].
* Since: 2.80
*/
ffi_closure *
gi_callable_info_create_closure (GICallableInfo *callable_info,
@ -419,7 +425,11 @@ gi_callable_info_create_closure (GICallableInfo *callable_info,
* @callable_info: a callable info from a typelib
* @closure: ffi closure
*
* Gets callable code from ffi_closure prepared by gi_callable_info_create_closure()
* Gets callable code from `ffi_closure` prepared by
* [method@GIRepository.CallableInfo.create_closure].
*
* Returns: (transfer none): native address
* Since: 2.80
*/
gpointer *
gi_callable_info_get_closure_native_address (GICallableInfo *callable_info,
@ -432,9 +442,12 @@ gi_callable_info_get_closure_native_address (GICallableInfo *callable_info,
/**
* gi_callable_info_destroy_closure:
* @callable_info: a callable info from a typelib
* @closure: ffi closure
* @closure: (transfer full): ffi closure
*
* Frees a ffi_closure returned from gi_callable_info_create_closure()
* Frees a `ffi_closure` returned from
* [method@GIRepository.CallableInfo.create_closure].
*
* Since: 2.80
*/
void
gi_callable_info_destroy_closure (GICallableInfo *callable_info,

40
girepository/girffi.h
View File

@ -34,38 +34,48 @@ G_BEGIN_DECLS
/**
* GIFFIClosureCallback:
* @Param1: TODO
* @Param2: TODO
* @Param3: TODO
* @Param4: TODO
* @cif: the `ffi_cif` passed to
* [method@GIRepository.CallableInfo.create_closure]
* @ret: (out caller-allocates): a pointer to the memory used for the function’s
* return value
* @args: a vector of pointers to memory holding the arguments to the function
* @user_data: the user data passed to
* [method@GIRepository.CallableInfo.create_closure]
*
* TODO
* The function which will be called when a closure created with
* [method@GIRepository.CallableInfo.create_closure] is invoked.
*
* The value of @ret is undefined if the function returns `void`.
*
* Since: 2.80
*/
typedef void (*GIFFIClosureCallback) (ffi_cif *,
void *,
void **,
void *);
typedef void (*GIFFIClosureCallback) (ffi_cif *cif,
void *ret,
void **args,
void *user_data);
/**
* GIFunctionInvoker:
* @cif: the cif
* @native_address: the native address
*
* TODO
* Structure containing the data necessary to invoke a callable function.
*
* Since: 2.80
*/
typedef struct _GIFunctionInvoker GIFunctionInvoker;
struct _GIFunctionInvoker {
typedef struct {
ffi_cif cif;
gpointer native_address;
/*< private >*/
gpointer padding[3];
};
} GIFunctionInvoker;
/**
* GIFFIReturnValue:
*
* TODO
* The type of a return value from a callable invocation closure.
*
* Since: 2.80
*/
typedef GIArgument GIFFIReturnValue;

2
girepository/girmodule.c
View File

@ -93,6 +93,8 @@ gi_ir_module_free (GIIrModule *module)
* @args: Remaining arguments
*
* Report a fatal error, then exit.
*
* Since: 2.80
*/
void
gi_ir_module_fatal (GIIrTypelibBuild *build,

2
girepository/giroffsets.c
View File

@ -509,6 +509,8 @@ check_needs_computation (GIIrTypelibBuild *build,
* If a node is a a structure or union, makes sure that the field
* offsets have been computed, and also computes the overall size and
* alignment for the type.
*
* Since: 2.80
*/
void
gi_ir_node_compute_offsets (GIIrTypelibBuild *build,

29
girepository/girparser.c
View File

@ -3674,15 +3674,17 @@ cleanup (GMarkupParseContext *context,
* gi_ir_parser_parse_string:
* @parser: a #GIIrParser
* @namespace: the namespace of the string
* @filename: (allow-none): Path to parsed file, or %NULL
* @buffer: the data containing the XML
* @length: length of the data
* @error: return location for a #GError, or %NULL
* @filename: (nullable) (type filename): Path to parsed file, or `NULL`
* @buffer: (array length=length): the data containing the XML
* @length: length of the data, in bytes
* @error: return location for a [type@GLib.Error], or `NULL`
*
* Parse a string that holds a complete GIR XML file, and return a list of a
* a #GirModule for each &lt;namespace/&gt; element within the file.
* a [class@GIRepository.IrModule] for each `<namespace/>` element within the
* file.
*
* Returns: (transfer none): a new #GirModule
* Returns: (transfer none): a new [class@GIRepository.IrModule]
* Since: 2.80
*/
GIIrModule *
gi_ir_parser_parse_string (GIIrParser *parser,
@ -3757,14 +3759,17 @@ gi_ir_parser_parse_string (GIIrParser *parser,
/**
* gi_ir_parser_parse_file:
* @parser: a #GIIrParser
* @filename: filename to parse
* @error: return location for a #GError, or %NULL
* @filename: (type filename): filename to parse
* @error: return location for a [type@GLib.Error], or `NULL`
*
* Parse GIR XML file, and return a list of a a #GirModule for each
* &lt;namespace/&gt; element within the file.
* Parse the given GIR XML file, and return a list of a
* [class@GIRepository.IrModule] for each `<namespace/>` element within the
* file.
*
* Returns: (transfer container): a newly allocated list of #GIIrModule. The modules themselves
* are owned by the #GIIrParser and will be freed along with the parser.
* Returns: (transfer container): a newly allocated list of
* [class@GIRepository.IrModule]s. The modules themselves
* are owned by the `GIIrParser` and will be freed along with the parser.
* Since: 2.80
*/
GIIrModule *
gi_ir_parser_parse_file (GIIrParser *parser,

6
girepository/girwriter.c
View File

@ -1316,15 +1316,17 @@ write_union_info (const gchar *ns,
}
/*
/**
* gi_ir_writer_write:
* @filename: filename to write to
* @filename: (type filename): filename to write to
* @ns: GIR namespace to write
* @needs_prefix: if the filename needs prefixing
* @show_all: if field size calculations should be included
*
* Writes the output of a typelib represented by @ns
* into a GIR xml file named @filename.
*
* Since: 2.80
*/
void
gi_ir_writer_write (const char *filename,

41
girepository/gisignalinfo.c
View File

@ -33,27 +33,30 @@
#include "gisignalinfo.h"
/**
* SECTION:gisignalinfo
* @title: GISignalInfo
* @short_description: Struct representing a signal
* GISignalInfo:
*
* GISignalInfo represents a signal.
* `GISignalInfo` represents a signal.
*
* It's a sub-struct of #GICallableInfo and contains a set of flags and
* a class closure.
* It’s a sub-struct of [class@GIRepository.CallableInfo] and contains a set of
* flags and a class closure.
*
* See #GICallableInfo for information on how to retreive arguments
* and other metadata from the signal.
* See [class@GIRepository.CallableInfo] for information on how to retrieve
* arguments and other metadata from the signal.
*
* Since: 2.80
*/
/**
* gi_signal_info_get_flags:
* @info: a #GISignalInfo
*
* Obtain the flags for this signal info. See #GSignalFlags for
* more information about possible flag values.
* Obtain the flags for this signal info.
*
* See [flags@GObject.SignalFlags] for more information about possible flag
* values.
*
* Returns: the flags
* Since: 2.80
*/
GSignalFlags
gi_signal_info_get_flags (GISignalInfo *info)
@ -96,11 +99,14 @@ gi_signal_info_get_flags (GISignalInfo *info)
* gi_signal_info_get_class_closure:
* @info: a #GISignalInfo
*
* Obtain the class closure for this signal if one is set. The class
* closure is a virtual function on the type that the signal belongs to.
* If the signal lacks a closure %NULL will be returned.
* Obtain the class closure for this signal if one is set.
*
* Returns: (transfer full): the class closure or %NULL
* The class closure is a virtual function on the type that the signal belongs
* to. If the signal lacks a closure, `NULL` will be returned.
*
* Returns: (transfer full) (nullable): the class closure, or `NULL` if none is
* set
* Since: 2.80
*/
GIVFuncInfo *
gi_signal_info_get_class_closure (GISignalInfo *info)
@ -123,10 +129,11 @@ gi_signal_info_get_class_closure (GISignalInfo *info)
* gi_signal_info_true_stops_emit:
* @info: a #GISignalInfo
*
* Obtain if the returning true in the signal handler will
* stop the emission of the signal.
* Obtain if the returning `TRUE` in the signal handler will stop the emission
* of the signal.
*
* Returns: %TRUE if returning true stops the signal emission
* Returns: `TRUE` if returning `TRUE` stops the signal emission
* Since: 2.80
*/
gboolean
gi_signal_info_true_stops_emit (GISignalInfo *info)

6
girepository/gisignalinfo.h
View File

@ -34,10 +34,12 @@
G_BEGIN_DECLS
/**
* GI_IS_SIGNAL_INFO
* GI_IS_SIGNAL_INFO:
* @info: an info structure
*
* Checks if @info is a #GISignalInfo.
* Checks if @info is a [class@GIRepository.SignalInfo].
*
* Since: 2.80
*/
#define GI_IS_SIGNAL_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_SIGNAL)

67
girepository/gistructinfo.c
View File

@ -35,13 +35,13 @@
#include "gistructinfo.h"
/**
* SECTION:gistructinfo
* @title: GIStructInfo
* @short_description: Struct representing a C structure
* GIStructInfo:
*
* GIStructInfo represents a generic C structure type.
* `GIStructInfo` represents a generic C structure type.
*
* A structure has methods and fields.
*
* Since: 2.80
*/
/**
@ -51,6 +51,7 @@
* Obtain the number of fields this structure has.
*
* Returns: number of fields
* Since: 2.80
*/
guint
gi_struct_info_get_n_fields (GIStructInfo *info)
@ -68,7 +69,8 @@ gi_struct_info_get_n_fields (GIStructInfo *info)
*
* Obtain the offset of the specified field.
*
* Returns: field offset in bytes
* Returns: field offset, in bytes
* Since: 2.80
*/
static gint32
gi_struct_get_field_offset (GIStructInfo *info,
@ -97,8 +99,9 @@ gi_struct_get_field_offset (GIStructInfo *info,
*
* Obtain the type information for field with specified index.
*
* Returns: (transfer full): the #GIFieldInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFieldInfo *
gi_struct_info_get_field (GIStructInfo *info,
@ -117,9 +120,10 @@ gi_struct_info_get_field (GIStructInfo *info,
*
* Obtain the type information for field named @name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.FieldInfo], or
* `NULL` if not found. Free it with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
* Returns: (transfer full): the #GIFieldInfo or %NULL if not found,
* free it with gi_base_info_unref() when done.
*/
GIFieldInfo *
gi_struct_info_find_field (GIStructInfo *info,
@ -159,6 +163,7 @@ gi_struct_info_find_field (GIStructInfo *info,
* Obtain the number of methods this structure has.
*
* Returns: number of methods
* Since: 2.80
*/
guint
gi_struct_info_get_n_methods (GIStructInfo *info)
@ -176,8 +181,9 @@ gi_struct_info_get_n_methods (GIStructInfo *info)
*
* Obtain the type information for method with specified index.
*
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_struct_info_get_method (GIStructInfo *info,
@ -200,8 +206,10 @@ gi_struct_info_get_method (GIStructInfo *info,
*
* Obtain the type information for method named @name.
*
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* or `NULL` if none was found. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_struct_info_find_method (GIStructInfo *info,
@ -221,7 +229,8 @@ gi_struct_info_find_method (GIStructInfo *info,
*
* Obtain the total size of the structure.
*
* Returns: size of the structure in bytes
* Returns: size of the structure, in bytes
* Since: 2.80
*/
gsize
gi_struct_info_get_size (GIStructInfo *info)
@ -238,7 +247,8 @@ gi_struct_info_get_size (GIStructInfo *info)
*
* Obtain the required alignment of the structure.
*
* Returns: required alignment in bytes
* Returns: required alignment, in bytes
* Since: 2.80
*/
gsize
gi_struct_info_get_alignment (GIStructInfo *info)
@ -251,11 +261,13 @@ gi_struct_info_get_alignment (GIStructInfo *info)
/**
* gi_struct_info_is_foreign:
* @info: TODO
* @info: a #GIStructInfo
*
* TODO
* Gets whether the structure is foreign, i.e. if it’s expected to be overridden
* by a native language binding instead of relying of introspected bindings.
*
* Returns: TODO
* Returns: `TRUE` if the structure is foreign
* Since: 2.80
*/
gboolean
gi_struct_info_is_foreign (GIStructInfo *info)
@ -270,11 +282,14 @@ gi_struct_info_is_foreign (GIStructInfo *info)
* gi_struct_info_is_gtype_struct:
* @info: a #GIStructInfo
*
* Return true if this structure represents the "class structure" for some
* #GObject or #GInterface. This function is mainly useful to hide this kind of structure
* from generated public APIs.
* Return true if this structure represents the ‘class structure’ for some
* [class@GObject.Object] or `GInterface`.
*
* Returns: %TRUE if this is a class struct, %FALSE otherwise
* This function is mainly useful to hide this kind of structure from generated
* public APIs.
*
* Returns: `TRUE` if this is a class struct, `FALSE` otherwise
* Since: 2.80
*/
gboolean
gi_struct_info_is_gtype_struct (GIStructInfo *info)
@ -291,8 +306,8 @@ gi_struct_info_is_gtype_struct (GIStructInfo *info)
*
* Retrieves the name of the copy function for @info, if any is set.
*
* Returns: (transfer none) (nullable): the name of the copy function
*
* Returns: (transfer none) (nullable): the name of the copy function, or `NULL`
* if the structure has no copy function
* Since: 2.80
*/
const char *
@ -318,8 +333,8 @@ gi_struct_info_get_copy_function_name (GIStructInfo *info)
*
* Retrieves the name of the free function for @info, if any is set.
*
* Returns: (transfer none) (nullable): the name of the free function
*
* Returns: (transfer none) (nullable): the name of the free function, or `NULL`
* if the structure has no free function
* Since: 2.80
*/
const char *

6
girepository/gistructinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_STRUCT_INFO
* GI_IS_STRUCT_INFO:
* @info: an info structure
*
* Checks if @info is a #GIStructInfo.
* Checks if @info is a [class@GIRepository.StructInfo].
*
* Since: 2.80
*/
#define GI_IS_STRUCT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_STRUCT)

55
girepository/gitypeinfo.c
View File

@ -65,7 +65,7 @@
* (i.e. only if the type of the C function’s formal parameter is a pointer to a
* pointer).
*
* Returns: true if it is a pointer
* Returns: `TRUE` if it is a pointer
* Since: 2.80
*/
gboolean
@ -128,9 +128,10 @@ gi_type_info_get_tag (GITypeInfo *info)
* @info: a #GITypeInfo
* @n: index of the parameter
*
* Obtain the parameter type @n, or `-1` if the type is not an array.
* Obtain the parameter type @n, or `NULL` if the type is not an array.
*
* Returns: (transfer full) (nullable): the param type info
* Returns: (transfer full) (nullable): the param type info, or `NULL` if the
* type is not an array
* Since: 2.80
*/
GITypeInfo *
@ -173,13 +174,16 @@ gi_type_info_get_param_type (GITypeInfo *info,
*
* For types which have `GI_TYPE_TAG_INTERFACE` such as [class@GObject.Object]s
* and boxed values, this function returns full information about the referenced
* type. You can then inspect the type of the returned
* [class@GIRepository.BaseInfo] to further query whether it is a concrete
* [class@GObject.Object], an interface, a structure, etc., using
* type.
*
* You can then inspect the type of the returned [class@GIRepository.BaseInfo]
* to further query whether it is a concrete [class@GObject.Object], an
* interface, a structure, etc., using
* [method@GIRepository.BaseInfo.get_info_type].
*
* Returns: (transfer full) (nullable): the [class@GIRepository.BaseInfo], or
* Returns: (transfer full) (nullable): The [class@GIRepository.BaseInfo], or
* `NULL`. Free it with gi_base_info_unref() when done.
* Since: 2.80
*/
GIBaseInfo *
gi_type_info_get_interface (GITypeInfo *info)
@ -230,9 +234,11 @@ gi_type_info_get_interface (GITypeInfo *info)
* @info: a #GITypeInfo
*
* Obtain the position of the argument which gives the array length of the type.
*
* The type tag must be a `GI_TYPE_TAG_ARRAY` or `-1` will be returned.
*
* Returns: the array length argument index, or `-1` if the type is not an array
* or it has no length argument
* Since: 2.80
*/
gint
@ -264,10 +270,11 @@ gi_type_info_get_array_length_index (GITypeInfo *info)
* gi_type_info_get_array_fixed_size:
* @info: a #GITypeInfo
*
* Obtain the fixed array size of the type. The type tag must be a
* `GI_TYPE_TAG_ARRAY` or `-1` will be returned.
* Obtain the fixed array size of the type, in number of elements (not bytes).
*
* Returns: the size or `-1` if the type is not an array
* The type tag must be a `GI_TYPE_TAG_ARRAY` or `-1` will be returned.
*
* Returns: the size or `-1` if the type is not an array or it has no fixed size
* Since: 2.80
*/
gssize
@ -299,10 +306,11 @@ gi_type_info_get_array_fixed_size (GITypeInfo *info)
* gi_type_info_is_zero_terminated:
* @info: a #GITypeInfo
*
* Obtain if the last element of the array is `NULL`. The type tag must be a
* `GI_TYPE_TAG_ARRAY` or false will be returned.
* Obtain if the last element of the array is `NULL`.
*
* Returns: true if zero terminated
* The type tag must be a `GI_TYPE_TAG_ARRAY` or `FALSE` will be returned.
*
* Returns: `TRUE` if zero terminated
* Since: 2.80
*/
gboolean
@ -395,7 +403,11 @@ gi_type_info_get_storage_type (GITypeInfo *info)
* @storage_type: a [type@GIRepository.TypeTag] obtained from
* [method@GIRepository.TypeInfo.get_storage_type]
* @hash_pointer: a pointer, such as a [struct@GLib.HashTable] data pointer
* @arg: a [type@GIRepository.Argument] to fill in
* @arg: (out caller-allocates) (not nullable): a [type@GIRepository.Argument]
* to fill in
*
* Convert a data pointer from a GLib data structure to a
* [type@GIRepository.Argument].
*
* GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers.
@ -469,7 +481,10 @@ gi_type_tag_argument_from_hash_pointer (GITypeTag storage_type,
* gi_type_info_argument_from_hash_pointer:
* @info: a #GITypeInfo
* @hash_pointer: a pointer, such as a [struct@GLib.HashTable] data pointer
* @arg: a [type@GIRepository.Argument] to fill in
* @arg: (out caller-allocates): a [type@GIRepository.Argument] to fill in
*
* Convert a data pointer from a GLib data structure to a
* [type@GIRepository.Argument].
*
* GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers.
@ -500,7 +515,10 @@ gi_type_info_argument_from_hash_pointer (GITypeInfo *info,
* gi_type_tag_hash_pointer_from_argument:
* @storage_type: a [type@GIRepository.TypeTag] obtained from
* [method@GIRepository.TypeInfo.get_storage_type]
* @arg: A [type@GIRepository.Argument] with the value to stuff into a pointer
* @arg: a [type@GIRepository.Argument] with the value to stuff into a pointer
*
* Convert a [type@GIRepository.Argument] to data pointer for use in a GLib
* data structure.
*
* GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers.
@ -565,7 +583,10 @@ gi_type_tag_hash_pointer_from_argument (GITypeTag storage_type,
/**
* gi_type_info_hash_pointer_from_argument:
* @info: a #GITypeInfo
* @arg: A [struct@GIRepository.Argument] with the value to stuff into a pointer
* @arg: a [struct@GIRepository.Argument] with the value to stuff into a pointer
*
* Convert a [type@GIRepository.Argument] to data pointer for use in a GLib
* data structure.
*
* GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers.

84
girepository/gitypelib-internal.h
View File

@ -36,7 +36,7 @@ G_BEGIN_DECLS
* @short_description: Layout and accessors for typelib
* @stability: Stable
*
* The "typelib" is a binary, readonly, memory-mappable database
* The ‘typelib’ is a binary, readonly, memory-mappable database
* containing reflective information about a GObject library.
*
* What the typelib describes and the types used are the same for every
@ -60,7 +60,7 @@ G_BEGIN_DECLS
*
* The typelib has the following general format:
*
* |[<!-- language="C" -->
* ```
* typelib ::= header, section-index, directory, blobs, attributes, attributedata
*
* directory ::= list of entries
@ -69,13 +69,15 @@ G_BEGIN_DECLS
* blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
* attribute ::= offset, key, value
* attributedata ::= string data for attributes
* ]|
* ```
*
* Details
* ## Details
*
* We describe the fragments that make up the typelib in the form of C structs
* (although some fall short of being valid C structs since they contain
* multiple flexible arrays).
*
* Since: 2.80
*/
/*
@ -148,8 +150,11 @@ Changes since 0.1:
/**
* GI_IR_MAGIC:
*
* Identifying prefix for the typelib. This was inspired by XPCOM,
* which in turn borrowed from PNG.
* Identifying prefix for the typelib.
*
* This was inspired by XPCOM, which in turn borrowed from PNG.
*
* Since: 2.80
*/
#define GI_IR_MAGIC "GOBJ\nMETADATA\r\n\032"
@ -170,6 +175,8 @@ Changes since 0.1:
*
* The integral value of this enumeration appears in each "Blob" component of
* a typelib to identify its type.
*
* Since: 2.80
*/
typedef enum {
BLOB_TYPE_INVALID,
@ -276,6 +283,8 @@ _blob_is_registered_type (GITypelibBlobType blob_type)
*
* The header structure appears exactly once at the beginning of a typelib. It is a
* collection of meta-information, such as the number of entries and dependencies.
*
* Since: 2.80
*/
typedef struct {
gchar magic[16];
@ -327,6 +336,8 @@ typedef struct {
* @GI_SECTION_DIRECTORY_INDEX: TODO
*
* TODO
*
* Since: 2.80
*/
typedef enum {
GI_SECTION_END = 0,
@ -342,6 +353,8 @@ typedef enum {
* and may or may not be present in the typelib. Presently, just used
* for the directory index. This allows a form of dynamic extensibility
* with different tradeoffs from the format minor version.
*
* Since: 2.80
*/
typedef struct {
guint32 id;
@ -363,6 +376,8 @@ typedef struct {
*
* All blobs pointed to by a directory entry start with the same layout for
* the first 8 bytes (the reserved flags may be used by some blob types)
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -382,6 +397,8 @@ typedef struct {
* @tag: A #GITypeTag
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint reserved : 8;
@ -419,6 +436,8 @@ union _SimpleTypeBlob
* In this case, the integer is actually an offset into the directory (see
* above). Because the header is larger than 2^8=256 bits, all offsets will
* have one of the upper 24 bits set.
*
* Since: 2.80
*/
typedef union _SimpleTypeBlob SimpleTypeBlob;
@ -466,6 +485,8 @@ typedef union _SimpleTypeBlob SimpleTypeBlob;
* Types are specified by four bytes. If the three high bytes are zero,
* the low byte describes a basic type, otherwise the 32bit number is an
* offset which points to a TypeBlob.
*
* Since: 2.80
*/
typedef struct {
guint32 name;
@ -511,6 +532,8 @@ typedef struct {
* @arguments: An array of ArgBlob for the arguments of the function.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
SimpleTypeBlob return_type;
@ -539,6 +562,8 @@ typedef struct {
* #CallbackBlob, #SignalBlob.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type; /* 1 */
@ -576,6 +601,8 @@ typedef struct {
* @reserved2: Reserved for future use.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type; /* 1 */
@ -610,6 +637,8 @@ typedef struct {
* the return value type.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type; /* 2 */
@ -629,6 +658,8 @@ typedef struct {
* @interface: Index of the directory entry for the interface.
*
* If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
*
* Since: 2.80
*/
typedef struct {
guint8 pointer :1;
@ -644,6 +675,8 @@ typedef struct {
* @size: TODO
*
* TODO
*
* Since: 2.80
*/
typedef union {
guint16 length;
@ -669,6 +702,8 @@ typedef union {
* @type: TODO
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 pointer :1;
@ -696,6 +731,8 @@ typedef struct {
* @type: Describes the type of the list elements.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint8 pointer :1;
@ -718,6 +755,8 @@ typedef struct {
* @domains: TODO
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint8 pointer :1;
@ -739,6 +778,8 @@ typedef struct {
* @value: The numerical value
*
* Values commonly occur in enums and flags.
*
* Since: 2.80
*/
typedef struct {
guint32 deprecated : 1;
@ -763,6 +804,8 @@ typedef struct {
* @type: The type of the field.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint32 name;
@ -792,6 +835,8 @@ typedef struct {
* type.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -827,6 +872,8 @@ typedef struct {
* the contents of this struct type
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -876,6 +923,8 @@ typedef struct {
* @discriminator_type: Type of the discriminator
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -918,6 +967,8 @@ typedef struct {
* @values: TODO
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -966,6 +1017,8 @@ typedef struct {
* @type: Describes the type of the property.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint32 name;
@ -1007,6 +1060,8 @@ typedef struct {
* and the return value type.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 deprecated : 1;
@ -1056,6 +1111,8 @@ typedef struct {
* the return value type.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint32 name;
@ -1116,6 +1173,8 @@ typedef struct {
* interfaces.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type; /* 7 */
@ -1176,6 +1235,8 @@ typedef struct {
* interfaces.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -1215,6 +1276,8 @@ typedef struct {
* @reserved2: Reserved for future use.
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint16 blob_type;
@ -1239,6 +1302,8 @@ typedef struct {
* @value: The value of the attribute (also a string)
*
* TODO
*
* Since: 2.80
*/
typedef struct {
guint32 offset;
@ -1283,6 +1348,7 @@ void gi_typelib_check_sanity (void);
* TODO
*
* Returns: TODO
* Since: 2.80
*/
#define gi_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)])
@ -1296,6 +1362,8 @@ void gi_typelib_check_sanity (void);
* @GI_TYPELIB_ERROR_INVALID_BLOB: a typelib blob is invalid
*
* A error set while validating the #GITypelib
*
* Since: 2.80
*/
typedef enum
{
@ -1310,6 +1378,8 @@ typedef enum
* GI_TYPELIB_ERROR:
*
* TODO
*
* Since: 2.80
*/
#define GI_TYPELIB_ERROR (gi_typelib_error_quark ())
@ -1329,6 +1399,8 @@ AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info,
* GITypelibHashBuilder:
*
* TODO
*
* Since: 2.80
*/
typedef struct _GITypelibHashBuilder GITypelibHashBuilder;

103
girepository/gitypelib.c
View File

@ -145,12 +145,13 @@ get_type_blob (GITypelib *typelib,
/**
* gi_typelib_get_dir_entry:
* @typelib: TODO
* @index: TODO
* @typelib: a #GITypelib
* @index: index to retrieve
*
* TODO
* Get the typelib directory entry at the given @index.
*
* Returns: TODO
* Returns: (transfer none): a `DirEntry`
* Since: 2.80
*/
DirEntry *
gi_typelib_get_dir_entry (GITypelib *typelib,
@ -183,12 +184,14 @@ get_section_by_id (GITypelib *typelib,
/**
* gi_typelib_get_dir_entry_by_name:
* @typelib: TODO
* @name: TODO
* @typelib: a #GITypelib
* @name: name to look up
*
* TODO
* Get the typelib directory entry which has @name.
*
* Returns: TODO
* Returns: (transfer none) (nullable): entry corresponding to @name, or `NULL`
* if none was found
* Since: 2.80
*/
DirEntry *
gi_typelib_get_dir_entry_by_name (GITypelib *typelib,
@ -229,12 +232,15 @@ gi_typelib_get_dir_entry_by_name (GITypelib *typelib,
/**
* gi_typelib_get_dir_entry_by_gtype_name:
* @typelib: TODO
* @gtype_name: TODO
* @typelib: a #GITypelib
* @gtype_name: name of a [type@GObject.Type] to look up
*
* TODO
* Get the typelib directory entry for the [type@GObject.Type] with the given
* @gtype_name.
*
* Returns: TODO
* Returns: (transfer none) (nullable): entry corresponding to @gtype_name, or
* `NULL` if none was found
* Since: 2.80
*/
DirEntry *
gi_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib,
@ -323,12 +329,14 @@ strsplit_iter_clear (StrSplitIter *iter)
/**
* gi_typelib_matches_gtype_name_prefix:
* @typelib: TODO
* @gtype_name: TODO
* @typelib: a #GITypelib
* @gtype_name: name of a [type@GObject.Type]
*
* TODO
* Check whether the symbol prefix for @typelib is a prefix of the given
* @gtype_name.
*
* Returns: TODO
* Returns: `TRUE` if the prefix for @typelib prefixes @gtype_name
* Since: 2.80
*/
gboolean
gi_typelib_matches_gtype_name_prefix (GITypelib *typelib,
@ -377,12 +385,15 @@ gi_typelib_matches_gtype_name_prefix (GITypelib *typelib,
/**
* gi_typelib_get_dir_entry_by_error_domain:
* @typelib: TODO
* @error_domain: TODO
* @typelib: a #GITypelib
* @error_domain: name of a [type@GLib.Error] domain to look up
*
* TODO
* Get the typelib directory entry for the [type@GLib.Error] domain with the
* given @error_domain name.
*
* Returns: TODO
* Returns: (transfer none) (nullable): entry corresponding to @error_domain, or
* `NULL` if none was found
* Since: 2.80
*/
DirEntry *
gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
@ -417,7 +428,10 @@ gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
/**
* gi_typelib_check_sanity:
*
* TODO
* Check compile-time sizes of various typelib file format types are as
* expected.
*
* Since: 2.80
*/
void
gi_typelib_check_sanity (void)
@ -2180,12 +2194,14 @@ prefix_with_context (GError **error,
/**
* gi_typelib_validate:
* @typelib: TODO
* @error: TODO
* @typelib: a #GITypelib
* @error: return location for a [type@GLib.Error], or `NULL`
*
* TODO
* Check whether @typelib is well-formed, i.e. that the file is not corrupt or
* truncated.
*
* Returns: TODO
* Returns: `TRUE` if @typelib is well-formed, `FALSE` otherwise
* Since: 2.80
*/
gboolean
gi_typelib_validate (GITypelib *typelib,
@ -2219,9 +2235,10 @@ gi_typelib_validate (GITypelib *typelib,
/**
* gi_typelib_error_quark:
*
* TODO
* Get the quark representing the [type@GIRepository.TypelibError] error domain.
*
* Returns: TODO
* Returns: quark representing the error domain
* Since: 2.80
*/
GQuark
gi_typelib_error_quark (void)
@ -2240,15 +2257,17 @@ static GSList *library_paths;
*
* Prepends @directory to the search path that is used to
* search shared libraries referenced by imported namespaces.
*
* Multiple calls to this function all contribute to the final
* list of paths.
* The list of paths is unique and shared for all #GIRepository
* instances across the process, but it doesn't affect namespaces
* imported before the call.
*
* The list of paths is unique and shared for all
* [class@GIRepository.Repository] instances across the process, but it doesn’t
* affect namespaces imported before the call.
*
* If the library is not found in the directories configured
* in this way, loading will fall back to the system library
* path (ie. LD_LIBRARY_PATH and DT_RPATH in ELF systems).
* path (i.e. `LD_LIBRARY_PATH` and `DT_RPATH` in ELF systems).
* See the documentation of your dynamic linker for full details.
*
* Since: 2.80
@ -2379,15 +2398,15 @@ gi_typelib_ensure_open (GITypelib *typelib)
/**
* gi_typelib_new_from_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib
* @len: length of memory chunk containing the typelib
* @error: a #GError
* @len: length of memory chunk containing the typelib, in bytes
* @error: a [type@GLib.Error]
*
* Creates a new `GITypelib` from a memory location.
* Creates a new [type@GIRepository.Typelib] from a memory location.
*
* The memory block pointed to by @typelib will be automatically freed when the
* repository is destroyed.
*
* Returns: (transfer full): the new #GITypelib
* Returns: (transfer full): the new [type@GIRepository.Typelib]
* Since: 2.80
*/
GITypelib *
@ -2413,11 +2432,11 @@ gi_typelib_new_from_memory (guint8 *memory,
* gi_typelib_new_from_const_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib
* @len: length of memory chunk containing the typelib
* @error: a #GError
* @error: a [type@GLib.Error]
*
* Creates a new `GITypelib` from a memory location.
* Creates a new [type@GIRepository.Typelib] from a memory location.
*
* Returns: (transfer full): the new #GITypelib
* Returns: (transfer full): the new [type@GIRepository.Typelib]
* Since: 2.80
*/
GITypelib *
@ -2445,9 +2464,9 @@ gi_typelib_new_from_const_memory (const guchar *memory,
* the repository is destroyed
* @error: a #GError
*
* Creates a new `GITypelib` from a [type@GLib.MappedFile].
* Creates a new [type@GIRepository.Typelib] from a [type@GLib.MappedFile].
*
* Returns: (transfer full): the new #GITypelib
* Returns: (transfer full): the new [type@GIRepository.Typelib]
* Since: 2.80
*/
GITypelib *
@ -2474,7 +2493,7 @@ gi_typelib_new_from_mapped_file (GMappedFile *mfile,
* gi_typelib_free:
* @typelib: (transfer full): a #GITypelib
*
* Free a `GITypelib`.
* Free a [type@GIRepository.Typelib].
*
* Since: 2.80
*/
@ -2518,7 +2537,7 @@ gi_typelib_get_namespace (GITypelib *typelib)
*
* Loads a symbol from a `GITypelib`.
*
* Returns: true on success
* Returns: `TRUE` on success
* Since: 2.80
*/
gboolean

234
girepository/gitypes.h
View File

@ -138,61 +138,74 @@ union _GIArgument
/**
* GIArgument:
* @v_boolean: TODO
* @v_int8: TODO
* @v_uint8: TODO
* @v_int16: TODO
* @v_uint16: TODO
* @v_int32: TODO
* @v_uint32: TODO
* @v_int64: TODO
* @v_uint64: TODO
* @v_float: TODO
* @v_double: TODO
* @v_short: TODO
* @v_ushort: TODO
* @v_int: TODO
* @v_uint: TODO
* @v_long: TODO
* @v_ulong: TODO
* @v_ssize: TODO
* @v_size: TODO
* @v_string: TODO
* @v_pointer: TODO
* @v_boolean: boolean value
* @v_int8: 8-bit signed integer value
* @v_uint8: 8-bit unsigned integer value
* @v_int16: 16-bit signed integer value
* @v_uint16: 16-bit unsigned integer value
* @v_int32: 32-bit signed integer value
* @v_uint32: 32-bit unsigned integer value
* @v_int64: 64-bit signed integer value
* @v_uint64: 64-bit unsigned integer value
* @v_float: single float value
* @v_double: double float value
* @v_short: signed short integer value
* @v_ushort: unsigned short integer value
* @v_int: signed integer value
* @v_uint: unsigned integer value
* @v_long: signed long integer value
* @v_ulong: unsigned long integer value
* @v_ssize: sized `size_t` value
* @v_size: unsigned `size_t` value
* @v_string: nul-terminated string value
* @v_pointer: arbitrary pointer value
*
* Stores an argument of varying type
* Stores an argument of varying type.
*
* Since: 2.80
*/
typedef union _GIArgument GIArgument;
/**
* GIInfoType:
* @GI_INFO_TYPE_INVALID: invalid type
* @GI_INFO_TYPE_FUNCTION: function, see #GIFunctionInfo
* @GI_INFO_TYPE_CALLBACK: callback, see #GIFunctionInfo
* @GI_INFO_TYPE_STRUCT: struct, see #GIStructInfo
* @GI_INFO_TYPE_BOXED: boxed, see #GIStructInfo or #GIUnionInfo
* @GI_INFO_TYPE_ENUM: enum, see #GIEnumInfo
* @GI_INFO_TYPE_FLAGS: flags, see #GIEnumInfo
* @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo
* @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo
* @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo
* @GI_INFO_TYPE_INVALID_0: deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN.
* @GI_INFO_TYPE_UNION: union, see #GIUnionInfo
* @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo
* @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo
* @GI_INFO_TYPE_VFUNC: virtual function, see #GIVFuncInfo
* @GI_INFO_TYPE_PROPERTY: GObject property, see #GIPropertyInfo
* @GI_INFO_TYPE_FIELD: struct or union field, see #GIFieldInfo
* @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo
* @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo
* @GI_INFO_TYPE_FUNCTION: function, see [class@GIRepository.FunctionInfo]
* @GI_INFO_TYPE_CALLBACK: callback, see [class@GIRepository.FunctionInfo]
* @GI_INFO_TYPE_STRUCT: struct, see [class@GIRepository.StructInfo]
* @GI_INFO_TYPE_BOXED: boxed, see [class@GIRepository.StructInfo] or
* [class@GIRepository.UnionInfo]
* @GI_INFO_TYPE_ENUM: enum, see [class@GIRepository.EnumInfo]
* @GI_INFO_TYPE_FLAGS: flags, see [class@GIRepository.EnumInfo]
* @GI_INFO_TYPE_OBJECT: object, see [class@GIRepository.ObjectInfo]
* @GI_INFO_TYPE_INTERFACE: interface, see [class@GIRepository.InterfaceInfo]
* @GI_INFO_TYPE_CONSTANT: constant, see [class@GIRepository.ConstantInfo]
* @GI_INFO_TYPE_INVALID_0: deleted, used to be `GI_INFO_TYPE_ERROR_DOMAIN`.
* @GI_INFO_TYPE_UNION: union, see [class@GIRepository.UnionInfo]
* @GI_INFO_TYPE_VALUE: enum value, see [class@GIRepository.ValueInfo]
* @GI_INFO_TYPE_SIGNAL: signal, see [class@GIRepository.SignalInfo]
* @GI_INFO_TYPE_VFUNC: virtual function, see [class@GIRepository.VFuncInfo]
* @GI_INFO_TYPE_PROPERTY: [class@GObject.Object] property, see
* [class@GIRepository.PropertyInfo]
* @GI_INFO_TYPE_FIELD: struct or union field, see
* [class@GIRepository.FieldInfo]
* @GI_INFO_TYPE_ARG: argument of a function or callback, see
* [class@GIRepository.ArgInfo]
* @GI_INFO_TYPE_TYPE: type information, see [class@GIRepository.TypeInfo]
* @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
* the typelib, or any of its dependencies.
* the typelib, or any of its dependencies, see
* [class@GIRepository.UnresolvedInfo]
* @GI_INFO_TYPE_CALLABLE: an abstract type representing any callable (function,
* callback, vfunc) (Since: 2.80)
* callback, vfunc), see [class@GIRepository.CallableInfo]
* @GI_INFO_TYPE_REGISTERED_TYPE: an abstract type representing any registered
* type (enum, interface, object, struct, union) (Since: 2.80)
* type (enum, interface, object, struct, union), see
* [class@GIRepository.RegisteredTypeInfo]
*
* The type of a GIBaseInfo struct.
* The type of a [class@GIRepository.BaseInfo] struct.
*
* See [const@GIRepository.INFO_TYPE_N_TYPES] for the total number of elements
* in this enum.
*
* Since: 2.80
*/
typedef enum
{
@ -221,31 +234,47 @@ typedef enum
/* keep GI_INFO_TYPE_N_TYPES in sync with this */
} GIInfoType;
/**
* GI_INFO_TYPE_N_TYPES:
*
* Number of entries in [enum@GIRepository.InfoType].
*
* Since: 2.80
*/
#define GI_INFO_TYPE_N_TYPES (GI_INFO_TYPE_REGISTERED_TYPE + 1)
/**
* GITransfer:
* @GI_TRANSFER_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.
* @GI_TRANSFER_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
* (g_list_free()/g_hash_table_destroy() etc) of this transfer.
* @GI_TRANSFER_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.
* @GI_TRANSFER_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.
* @GI_TRANSFER_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 ([func@GLib.List.free],
* [func@GLib.HashTable.destroy], etc) of this transfer.
* @GI_TRANSFER_EVERYTHING: Transfer everything, e.g. 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.
*
* `GITransfer` specifies who’s responsible for freeing the resources after an
* ownership transfer is complete.
*
* 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.
* #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.
* 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.
*
* In the 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. Each container is freed differently, check the documentation for
* the types themselves for information on how to free them.
*
* Since: 2.80
*/
typedef enum {
GI_TRANSFER_NOTHING,
@ -255,11 +284,13 @@ typedef enum {
/**
* GIDirection:
* @GI_DIRECTION_IN: in argument.
* @GI_DIRECTION_OUT: out argument.
* @GI_DIRECTION_INOUT: in and out argument.
* @GI_DIRECTION_IN: ‘in’ argument.
* @GI_DIRECTION_OUT: ‘out’ argument.
* @GI_DIRECTION_INOUT: ‘in and out’ argument.
*
* The direction of a #GIArgInfo.
* The direction of a [class@GIRepository.ArgInfo].
*
* Since: 2.80
*/
typedef enum {
GI_DIRECTION_IN,
@ -270,19 +301,22 @@ typedef enum {
/**
* GIScopeType:
* @GI_SCOPE_TYPE_INVALID: The argument is not of callback type.
* @GI_SCOPE_TYPE_CALL: The callback and associated user_data is only
* @GI_SCOPE_TYPE_CALL: The callback and associated `user_data` is only
* used during the call to this function.
* @GI_SCOPE_TYPE_ASYNC: The callback and associated user_data is
* @GI_SCOPE_TYPE_ASYNC: The callback and associated `user_data` is
* only used until the callback is invoked, and the callback.
* is invoked always exactly once.
* @GI_SCOPE_TYPE_NOTIFIED: The callback and associated
* user_data is used until the caller is notfied via the destroy_notify.
* @GI_SCOPE_TYPE_FOREVER: The callback and associated user_data is
* `user_data` is used until the caller is notified via the
* [type@GLib.DestroyNotify].
* @GI_SCOPE_TYPE_FOREVER: The callback and associated `user_data` is
* used until the process terminates
*
* Scope type of a #GIArgInfo representing callback, determines how the
* callback is invoked and is used to decided when the invoke structs
* can be freed.
* Scope type of a [class@GIRepository.ArgInfo] representing callback,
* determines how the callback is invoked and is used to decided when the invoke
* structs can be freed.
*
* Since: 2.80
*/
typedef enum {
GI_SCOPE_TYPE_INVALID,
@ -306,19 +340,21 @@ typedef enum {
* @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
* @GI_TYPE_TAG_FLOAT: float
* @GI_TYPE_TAG_DOUBLE: double floating point
* @GI_TYPE_TAG_GTYPE: a #GType
* @GI_TYPE_TAG_GTYPE: a [type@GObject.Type]
* @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
* @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
* as the native filesystem is using.
* @GI_TYPE_TAG_ARRAY: an array
* @GI_TYPE_TAG_INTERFACE: an extended interface object
* @GI_TYPE_TAG_GLIST: a #GList
* @GI_TYPE_TAG_GSLIST: a #GSList
* @GI_TYPE_TAG_GHASH: a #GHashTable
* @GI_TYPE_TAG_ERROR: a #GError
* @GI_TYPE_TAG_GLIST: a [type@GLib.List]
* @GI_TYPE_TAG_GSLIST: a [type@GLib.SList]
* @GI_TYPE_TAG_GHASH: a [type@GLib.HashTable]
* @GI_TYPE_TAG_ERROR: a [type@GLib.Error]
* @GI_TYPE_TAG_UNICHAR: Unicode character
*
* The type tag of a #GITypeInfo.
* The type tag of a [class@GIRepository.TypeInfo].
*
* Since: 2.80
*/
typedef enum {
/* Basic types */
@ -352,18 +388,22 @@ typedef enum {
/**
* GI_TYPE_TAG_N_TYPES:
*
* TODO
* Number of entries in [enum@GIRepository.TypeTag].
*
* Since: 2.80
*/
#define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
/**
* GIArrayType:
* @GI_ARRAY_TYPE_C: a C array, char[] for instance
* @GI_ARRAY_TYPE_ARRAY: a @GArray array
* @GI_ARRAY_TYPE_PTR_ARRAY: a #GPtrArray array
* @GI_ARRAY_TYPE_BYTE_ARRAY: a #GByteArray array
* @GI_ARRAY_TYPE_C: a C array, `char[]` for instance
* @GI_ARRAY_TYPE_ARRAY: a [type@GLib.Array] array
* @GI_ARRAY_TYPE_PTR_ARRAY: a [type@GLib.PtrArray] array
* @GI_ARRAY_TYPE_BYTE_ARRAY: a [type@GLib.ByteArray] array
*
* The type of array in a #GITypeInfo.
* The type of array in a [class@GIRepository.TypeInfo].
*
* Since: 2.80
*/
typedef enum {
GI_ARRAY_TYPE_C,
@ -377,7 +417,9 @@ typedef enum {
* @GI_FIELD_IS_READABLE: field is readable.
* @GI_FIELD_IS_WRITABLE: field is writable.
*
* Flags for a #GIFieldInfo.
* Flags for a [class@GIRepository.FieldInfo].
*
* Since: 2.80
*/
typedef enum
@ -391,9 +433,11 @@ typedef enum
* @GI_VFUNC_MUST_CHAIN_UP: chains up to the parent type
* @GI_VFUNC_MUST_OVERRIDE: overrides
* @GI_VFUNC_MUST_NOT_OVERRIDE: does not override
* @GI_VFUNC_THROWS: Includes a #GError
* @GI_VFUNC_THROWS: includes a [type@GLib.Error]
*
* Flags of a #GIVFuncInfo struct.
* Flags of a [class@GIRepository.VFuncInfo] struct.
*
* Since: 2.80
*/
typedef enum
{
@ -407,12 +451,14 @@ typedef enum
* GIFunctionInfoFlags:
* @GI_FUNCTION_IS_METHOD: is a method.
* @GI_FUNCTION_IS_CONSTRUCTOR: is a constructor.
* @GI_FUNCTION_IS_GETTER: is a getter of a #GIPropertyInfo.
* @GI_FUNCTION_IS_SETTER: is a setter of a #GIPropertyInfo.
* @GI_FUNCTION_IS_GETTER: is a getter of a [class@GIRepository.PropertyInfo].
* @GI_FUNCTION_IS_SETTER: is a setter of a [class@GIRepository.PropertyInfo].
* @GI_FUNCTION_WRAPS_VFUNC: represents a virtual function.
* @GI_FUNCTION_THROWS: the function may throw an error.
*
* Flags for a #GIFunctionInfo struct.
* Flags for a [class@GIRepository.FunctionInfo] struct.
*
* Since: 2.80
*/
typedef enum
{

14
girepository/giunioninfo.c
View File

@ -134,9 +134,9 @@ gi_union_info_get_method (GIUnionInfo *info,
* gi_union_info_is_discriminated:
* @info: a #GIUnionInfo
*
* Return true if this union contains a discriminator field.
* Return `TRUE` if this union contains a discriminator field.
*
* Returns: true if this is a discriminated union, false otherwise
* Returns: `TRUE` if this is a discriminated union, `FALSE` otherwise
* Since: 2.80
*/
gboolean
@ -195,8 +195,9 @@ gi_union_info_get_discriminator_type (GIUnionInfo *info)
*
* If the union is not discriminated, `NULL` is returned.
*
* Returns: (transfer full) (nullable): the [type@GIRepository.ConstantInfo],
* free it with [method@GIRepository.BaseInfo.unref] when done.
* Returns: (transfer full) (nullable): The [type@GIRepository.ConstantInfo], or
* `NULL` if the union is not discriminated. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIConstantInfo *
@ -230,8 +231,9 @@ gi_union_info_get_discriminator (GIUnionInfo *info,
*
* Obtain the type information for the method named @name.
*
* Returns: (transfer full): the [type@GIRepository.FunctionInfo], free it
* with [method@GIRepository.BaseInfo.unref] when done.
* Returns: (transfer full) (nullable): The [type@GIRepository.FunctionInfo], or
* `NULL` if none was found. Free it with [method@GIRepository.BaseInfo.unref]
* when done.
* Since: 2.80
*/
GIFunctionInfo *

8
girepository/giunresolvedinfo.c
View File

@ -35,11 +35,11 @@
#include "giunresolvedinfo.h"
/**
* SECTION:giunresolved
* @title: GIUnresolvedInfo
* @short_description: Struct representing an unresolved symbol
* GIUnresolvedInfo:
*
* GIUnresolvedInfo represents an unresolved symbol.
* `GIUnresolvedInfo` represents an unresolved symbol.
*
* Since: 2.80
*/
void

6
girepository/giunresolvedinfo.h
View File

@ -32,10 +32,12 @@
G_BEGIN_DECLS
/**
* GI_IS_UNRESOLVED_INFO
* GI_IS_UNRESOLVED_INFO:
* @info: an info structure
*
* Checks if @info is a #GIUnresolvedInfo or derived from it.
* Checks if @info is a [class@GIRepository.UnresolvedInfo] or derived from it.
*
* Since: 2.80
*/
#define GI_IS_UNRESOLVED_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_UNRESOLVED)

51
girepository/givfuncinfo.c
View File

@ -37,7 +37,7 @@
/**
* GIVFuncInfo:
*
* `GIVfuncInfo` represents a virtual function.
* `GIVFuncInfo` represents a virtual function.
*
* A virtual function is a callable object that belongs to either a
* [type@GIRepository.ObjectInfo] or a [type@GIRepository.InterfaceInfo].
@ -114,8 +114,9 @@ gi_vfunc_info_get_flags (GIVFuncInfo *info)
* gi_vfunc_info_get_offset:
* @info: a #GIVFuncInfo
*
* Obtain the offset of the function pointer in the class struct. The value
* `0xFFFF` indicates that the struct offset is unknown.
* Obtain the offset of the function pointer in the class struct.
*
* The value `0xFFFF` indicates that the struct offset is unknown.
*
* Returns: the struct offset or `0xFFFF` if it’s unknown
* Since: 2.80
@ -143,7 +144,7 @@ gi_vfunc_info_get_offset (GIVFuncInfo *info)
* The signal comes from the object or interface to which
* this virtual function belongs.
*
* Returns: (transfer full) (nullable): the signal or `NULL` if none set
* Returns: (transfer full) (nullable): the signal, or `NULL` if none is set
* Since: 2.80
*/
GISignalInfo *
@ -172,8 +173,9 @@ gi_vfunc_info_get_signal (GIVFuncInfo *info)
*
* Not all virtuals will have invokers.
*
* Returns: (transfer full) (nullable): the [type@GIRepository.FunctionInfo] or
* `NULL`. Free it with gi_base_info_unref() when done.
* Returns: (transfer full) (nullable): The [type@GIRepository.FunctionInfo] or
* `NULL` if none is set. Free it with [method@GIRepository.BaseInfo.unref]
* when done.
* Since: 2.80
*/
GIFunctionInfo *
@ -206,13 +208,13 @@ gi_vfunc_info_get_invoker (GIVFuncInfo *info)
/**
* gi_vfunc_info_get_address:
* @info: a #GIVFuncInfo
* @implementor_gtype: #GType implementing this virtual function
* @error: return location for a #GError
* @implementor_gtype: [type@GObject.Type] implementing this virtual function
* @error: return location for a [type@GLib.Error], or `NULL`
*
* Looks up where inside the type struct of @implementor_gtype is the
* implementation for @info.
* Looks up where the implementation for @info is inside the type struct of
* @implementor_gtype.
*
* Returns: address to a function or `NULL` if an error happened
* Returns: address to a function
* Since: 2.80
*/
gpointer
@ -310,26 +312,29 @@ gi_vfunc_info_get_address (GIVFuncInfo *vfunc_info,
/**
* gi_vfunc_info_invoke: (skip)
* @info: a #GIVFuncInfo describing the virtual function to invoke
* @implementor: #GType of the type that implements this virtual function
* @implementor: [type@GObject.Type] of the type that implements this virtual
* function
* @in_args: (array length=n_in_args) (nullable): an array of
* [struct@GIRepository.Argument]s, one for each in parameter of @info. If
* there are no in parameter, @in_args can be `NULL`
* [struct@GIRepository.Argument]s, one for each ‘in’ parameter of @info. If
* there are no ‘in’ parameters, @in_args can be `NULL`
* @n_in_args: the length of the @in_args array
* @out_args: (array length=n_out_args) (nullable): an array of
* [struct@GIRepository.Argument]s, one for each out parameter of @info. If
* there are no out parameters, @out_args may be `NULL`
* [struct@GIRepository.Argument]s allocated by the caller, one for each
* ‘out’ parameter of @info. If there are no ‘out’ parameters, @out_args may
* be `NULL`
* @n_out_args: the length of the @out_args array
* @return_value: (nullable): return location for the return value of the
* function. If the function returns void, @return_value may be
* `NULL`
* @return_value: (out caller-allocates) (not optional) (nullable): return
* location for the return value from the vfunc; `NULL` may be returned if
* the vfunc returns that
* @error: return location for detailed error information, or `NULL`
*
* Invokes the function described in @info with the given
* arguments. Note that inout parameters must appear in both
* argument lists.
* arguments.
*
* Returns: true if the function has been invoked, false if an
* error occurred.
* Note that ‘inout’ parameters must appear in both argument lists.
*
* Returns: `TRUE` if the vfunc was executed successfully and didn’t throw
* a [type@GLib.Error]; `FALSE` if @error is set
* Since: 2.80
*/
gboolean