luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-27 14:36: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 */ /* GIArgInfo functions */
/** /**
* SECTION:giarginfo * GIArgInfo:
* @title: GIArgInfo
* @short_description: Struct representing an argument
* *
* 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: * gi_arg_info_get_direction:
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain the direction of the argument. Check #GIDirection for possible * Obtain the direction of the argument. Check [type@GIRepository.Direction]
* direction values. * for possible direction values.
* *
* Returns: the direction * Returns: The direction
* Since: 2.80
*/ */
GIDirection GIDirection
gi_arg_info_get_direction (GIArgInfo *info) 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 * Obtain if the argument is a return value. It can either be a
* parameter or a return value. * 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 gboolean
gi_arg_info_is_return_value (GIArgInfo *info) gi_arg_info_is_return_value (GIArgInfo *info)
@ -100,11 +102,14 @@ gi_arg_info_is_return_value (GIArgInfo *info)
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain if the argument is a pointer to a struct or object that will * Obtain if the argument is a pointer to a struct or object that will
* receive an output of a function. The default assumption for * receive an output of a function.
* %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 * 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 gboolean
gi_arg_info_is_caller_allocates (GIArgInfo *info) 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: * gi_arg_info_is_optional:
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain if the argument is optional. For 'out' arguments this means * Obtain if the argument is optional.
* that you can pass %NULL in order to ignore the result.
* *
* 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 gboolean
gi_arg_info_is_optional (GIArgInfo *info) gi_arg_info_is_optional (GIArgInfo *info)
@ -147,13 +155,15 @@ gi_arg_info_is_optional (GIArgInfo *info)
* gi_arg_info_may_be_null: * gi_arg_info_may_be_null:
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain if the type of the argument includes the possibility of %NULL. * 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.
* *
* 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 gboolean
gi_arg_info_may_be_null (GIArgInfo *info) 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. * 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 * Since: 2.80
*/ */
gboolean gboolean
@ -197,9 +207,10 @@ gi_arg_info_is_skip (GIArgInfo *info)
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain the ownership transfer for this argument. * 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 GITransfer
gi_arg_info_get_ownership_transfer (GIArgInfo *info) 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: * gi_arg_info_get_scope:
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtain the scope type for this argument. The scope type explains * Obtain the scope type for this argument.
* 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.
* *
* 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 GIScopeType
gi_arg_info_get_scope (GIArgInfo *info) 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 * Obtain the index of the user data argument. This is only valid
* for arguments which are callbacks. * 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 gint
gi_arg_info_get_closure_index (GIArgInfo *info) 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: * gi_arg_info_get_destroy_index:
* @info: a #GIArgInfo * @info: a #GIArgInfo
* *
* Obtains the index of the #GDestroyNotify argument. This is only valid * Obtains the index of the [type@GLib.DestroyNotify] argument. This is only
* for arguments which are callbacks. * 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 gint
gi_arg_info_get_destroy_index (GIArgInfo *info) 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. * Obtain the type information for @info.
* *
* Returns: (transfer full): the #GITypeInfo holding the type * Returns: (transfer full): The [class@GIRepository.TypeInfo] holding the type
* information for @info, free it with gi_base_info_unref() * information for @info, free it with [method@GIRepository.BaseInfo.unref]
* when done. * when done
* Since: 2.80
*/ */
GITypeInfo * GITypeInfo *
gi_arg_info_get_type_info (GIArgInfo *info) 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 * @type: (out caller-allocates): Initialized with information about type of @info
* *
* Obtain information about a the type of given argument @info; this * 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 * function is a variant of [method@GIRepository.ArgInfo.get_type_info] designed
* allocation. * for stack allocation.
* *
* The initialized @type must not be referenced after @info is deallocated. * The initialized @type must not be referenced after @info is deallocated.
*
* Since: 2.80
*/ */
void void
gi_arg_info_load_type (GIArgInfo *info, gi_arg_info_load_type (GIArgInfo *info,

6
girepository/giarginfo.h
View File

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

184
girepository/gicallableinfo.c
View File

@ -38,20 +38,20 @@
/* GICallableInfo functions */ /* GICallableInfo functions */
/** /**
* SECTION:gicallableinfo * GICallableInfo:
* @title: GICallableInfo
* @short_description: Struct representing a callable
* *
* GICallableInfo represents an entity which is callable. * `GICallableInfo` represents an entity which is callable.
* *
* Examples of callable are: * Examples of callable are:
* *
* - functions (#GIFunctionInfo) * - functions ([class@GIRepository.FunctionInfo])
* - virtual functions (#GIVFuncInfo) * - virtual functions ([class@GIRepository.VFuncInfo])
* - callbacks (#GICallbackInfo). * - callbacks ([class@GIRepository.CallbackInfo]).
* *
* A callable has a list of arguments (#GIArgInfo), a return type, * A callable has a list of arguments ([class@GIRepository.ArgInfo]), a return
* direction and a flag which decides if it returns null. * type, direction and a flag which decides if it returns `NULL`.
*
* Since: 2.80
*/ */
static guint32 static guint32
@ -86,10 +86,10 @@ signature_offset (GICallableInfo *info)
* gi_callable_info_can_throw_gerror: * gi_callable_info_can_throw_gerror:
* @info: a #GICallableInfo * @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 * Since: 2.80
* Returns: %TRUE if this #GICallableInfo can throw a #GError
*/ */
gboolean gboolean
gi_callable_info_can_throw_gerror (GICallableInfo *info) 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: * gi_callable_info_is_method:
* @info: a #GICallableInfo * @info: a #GICallableInfo
* *
* Determines if the callable info is a method. For #GIVFuncInfo<!-- -->s, * Determines if the callable info is a method.
* #GICallbackInfo<!-- -->s, and #GISignalInfo<!-- -->s,
* this is always true. Otherwise, this looks at the %GI_FUNCTION_IS_METHOD
* flag on the #GIFunctionInfo.
* *
* Concretely, this function returns whether gi_callable_info_get_n_args() * For [class@GIRepository.VFuncInfo]s, [class@GIRepository.CallbackInfo]s, and
* matches the number of arguments in the raw C method. For methods, there * [class@GIRepository.SignalInfo]s, this is always true. Otherwise, this looks
* is one more C argument than is exposed by introspection: the "self" * at the `GI_FUNCTION_IS_METHOD` flag on the [class@GIRepository.FunctionInfo].
* or "this" object.
* *
* 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 * Since: 2.80
*/ */
gboolean gboolean
@ -169,10 +170,11 @@ gi_callable_info_is_method (GICallableInfo *info)
* gi_callable_info_get_return_type: * gi_callable_info_get_return_type:
* @info: a #GICallableInfo * @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 * Returns: (transfer full): the [class@GIRepository.TypeInfo]. Free the struct
* gi_base_info_unref() when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GITypeInfo * GITypeInfo *
gi_callable_info_get_return_type (GICallableInfo *info) 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); return gi_type_info_new ((GIBaseInfo*)info, rinfo->typelib, offset);
} }
/** /**
* gi_callable_info_load_return_type: * gi_callable_info_load_return_type:
* @info: a #GICallableInfo * @info: a #GICallableInfo
* @type: (out caller-allocates): Initialized with return type of @info * @type: (out caller-allocates): Initialized with return type of @info
* *
* Obtain information about a return value of callable; this * Obtain information about a return value of callable; this
* function is a variant of gi_callable_info_get_return_type() designed for stack * function is a variant of [method@GIRepository.CallableInfo.get_return_type]
* allocation. * designed for stack allocation.
* *
* The initialized @type must not be referenced after @info is deallocated. * The initialized @type must not be referenced after @info is deallocated.
*
* Since: 2.80
*/ */
void void
gi_callable_info_load_return_type (GICallableInfo *info, 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: * gi_callable_info_may_return_null:
* @info: a #GICallableInfo * @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 gboolean
gi_callable_info_may_return_null (GICallableInfo *info) 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: * gi_callable_info_skip_return:
* @info: a #GICallableInfo * @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 gboolean
gi_callable_info_skip_return (GICallableInfo *info) gi_callable_info_skip_return (GICallableInfo *info)
@ -264,9 +269,11 @@ gi_callable_info_skip_return (GICallableInfo *info)
* @info: a #GICallableInfo * @info: a #GICallableInfo
* *
* See whether the caller owns the return value of this callable. * 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 * Returns: the transfer mode for the return value of the callable
* Since: 2.80
*/ */
GITransfer GITransfer
gi_callable_info_get_caller_owns (GICallableInfo *info) gi_callable_info_get_caller_owns (GICallableInfo *info)
@ -292,10 +299,11 @@ gi_callable_info_get_caller_owns (GICallableInfo *info)
* @info: a #GICallableInfo * @info: a #GICallableInfo
* *
* Obtains the ownership transfer for the instance argument. * 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 * Returns: the transfer mode of the instance argument
* Since: 2.80
*/ */
GITransfer GITransfer
gi_callable_info_get_instance_ownership_transfer (GICallableInfo *info) 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: * gi_callable_info_get_n_args:
* @info: a #GICallableInfo * @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. * Returns: The number of arguments this callable expects.
* Since: 2.80
*/ */
guint guint
gi_callable_info_get_n_args (GICallableInfo *info) 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. * Obtain information about a particular argument of this callable.
* *
* Returns: (transfer full): the #GIArgInfo. Free it with * Returns: (transfer full): the [class@GIRepository.ArgInfo]. Free it with
* gi_base_info_unref() when done. * [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIArgInfo * GIArgInfo *
gi_callable_info_get_arg (GICallableInfo *info, 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 * @arg: (out caller-allocates): Initialize with argument number @n
* *
* Obtain information about a particular argument of this callable; this * Obtain information about a particular argument of this callable; this
* function is a variant of gi_callable_info_get_arg() designed for stack * function is a variant of [method@GIRepository.CallableInfo.get_arg] designed
* allocation. * for stack allocation.
* *
* The initialized @arg must not be referenced after @info is deallocated. * The initialized @arg must not be referenced after @info is deallocated.
*
* Since: 2.80
*/ */
void void
gi_callable_info_load_arg (GICallableInfo *info, 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. * 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 * const gchar *
gi_callable_info_get_return_attribute (GICallableInfo *info, 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: * gi_callable_info_iterate_return_attributes:
* @info: a #GICallableInfo * @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 * @name: (out) (transfer none): Returned name, must not be freed
* @value: (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 * Iterate over all attributes associated with the return value.
* iterator structure is typically stack allocated, and must have its *
* first member initialized to %NULL. * 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 * Both the @name and @value should be treated as constants
* and must not be freed. * and must not be freed.
* *
* See gi_base_info_iterate_attributes() for an example of how to use a * See [method@GIRepository.BaseInfo.iterate_attributes] for an example of how
* similar API. * to use a similar API.
* *
* Returns: %TRUE if there are more attributes * Returns: `TRUE` if there are more attributes
* Since: 2.80
*/ */
gboolean gboolean
gi_callable_info_iterate_return_attributes (GICallableInfo *info, 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: * gi_type_tag_extract_ffi_return_value:
* @return_tag: #GITypeTag of the return value * @return_tag: [type@GIRepository.TypeTag] of the return value
* @interface_type: #GIInfoType of the underlying interface type * @interface_type: [type@GIRepository.InfoType] of the underlying interface type
* @ffi_value: pointer to #GIFFIReturnValue union containing the return value * @ffi_value: pointer to [type@GIRepository.FFIReturnValue] union containing
* from `ffi_call()` * the return value from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated #GIArgument * @arg: (out caller-allocates): pointer to an allocated
* [class@GIRepository.Argument]
* *
* Extract the correct bits from an `ffi_arg` return value into * 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 * See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
* *
* Also see `ffi_call(3)`: the storage requirements for return values * Also see [`ffi_call()`](man:ffi_call(3)): the storage requirements for return
* are "special". * values are ‘special’.
* *
* The @interface_type argument only applies if @return_tag is * 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 * Since: 2.80
*/ */
@ -550,23 +568,26 @@ gi_type_tag_extract_ffi_return_value (GITypeTag return_tag,
/** /**
* gi_type_info_extract_ffi_return_value: * gi_type_info_extract_ffi_return_value:
* @return_info: #GITypeInfo describing the return type * @return_info: [type@GIRepository.TypeInfo] describing the return type
* @ffi_value: pointer to #GIFFIReturnValue union containing the return value * @ffi_value: pointer to [type@GIRepository.FFIReturnValue] union containing
* from `ffi_call()` * the return value from `ffi_call()`
* @arg: (out caller-allocates): pointer to an allocated #GIArgument * @arg: (out caller-allocates): pointer to an allocated
* [class@GIRepository.Argument]
* *
* Extract the correct bits from an `ffi_arg` return value into * 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 * See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
* *
* Also see `ffi_call(3)`: the storage requirements for return values * Also see [`ffi_call()`](man:ffi_call(3)): the storage requirements for return
* are "special". * values are ‘special’.
*
* Since: 2.80
*/ */
void void
gi_type_info_extract_ffi_return_value (GITypeInfo *return_info, gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
GIFFIReturnValue *ffi_value, GIFFIReturnValue *ffi_value,
GIArgument *arg) GIArgument *arg)
{ {
GITypeTag return_tag = gi_type_info_get_tag (return_info); GITypeTag return_tag = gi_type_info_get_tag (return_info);
GIInfoType interface_type = GI_INFO_TYPE_INVALID; 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: * gi_callable_info_invoke:
* @info: TODO * @info: a #GICallableInfo
* @function: TODO * @function: function pointer to call
* @in_args: (array length=n_in_args): TODO * @in_args: (array length=n_in_args): array of ‘in’ arguments
* @n_in_args: TODO * @n_in_args: number of arguments in @in_args
* @out_args: (array length=n_out_args): TODO * @out_args: (array length=n_out_args): array of ‘out’ arguments allocated by
* @n_out_args: TODO * the caller, to be populated with outputted values
* @return_value: TODO * @n_out_args: number of arguments in @out_args
* @is_method: TODO * @return_value: (out caller-allocates) (not optional) (nullable): return
* @throws: TODO * location for the return value from the callable; `NULL` may be returned if
* @error: TODO * 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 gboolean
gi_callable_info_invoke (GICallableInfo *info, gi_callable_info_invoke (GICallableInfo *info,

6
girepository/gicallableinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_CALLABLE_INFO * GI_IS_CALLABLE_INFO:
* @info: an info structure * @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) \ #define GI_IS_CALLABLE_INFO(info) \
((gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FUNCTION) || \ ((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" #include "gicallbackinfo.h"
/** /**
* SECTION:gicallback * GICallbackInfo:
* @title: GICallbackInfo
* @short_description: Struct representing a callback
* *
* GICallbackInfo represents a callback. * `GICallbackInfo` represents a callback.
*
* Since: 2.80
*/ */
void void

6
girepository/gicallbackinfo.h
View File

@ -32,10 +32,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_CALLBACK_INFO * GI_IS_CALLBACK_INFO:
* @info: an info structure * @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) \ #define GI_IS_CALLBACK_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_CALLBACK) (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" #include "giconstantinfo.h"
/** /**
* SECTION:giconstantinfo * GIConstantInfo:
* @title: GIConstantInfo
* @short_description: Struct representing a constant
* *
* GIConstantInfo represents a constant. * `GIConstantInfo` represents a constant.
* *
* A constant has a type associated which can be obtained by calling * 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 * [method@GIRepository.ConstantInfo.get_type_info] – and a value – which can be
* calling gi_constant_info_get_value(). * obtained by calling [method@GIRepository.ConstantInfo.get_value].
*
* Since: 2.80
*/ */
/** /**
* gi_constant_info_get_type_info: * gi_constant_info_get_type_info:
* @info: a #GIConstantInfo * @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 * Returns: (transfer full): The [class@GIRepository.TypeInfo]. Free the struct
* gi_base_info_unref() when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GITypeInfo * GITypeInfo *
gi_constant_info_get_type_info (GIConstantInfo *info) gi_constant_info_get_type_info (GIConstantInfo *info)
@ -74,7 +74,7 @@ gi_constant_info_get_type_info (GIConstantInfo *info)
* @info: a #GIConstantInfo * @info: a #GIConstantInfo
* @value: the argument * @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 * Since: 2.80
*/ */
@ -101,14 +101,20 @@ gi_constant_info_free_value (GIConstantInfo *info,
/** /**
* gi_constant_info_get_value: (skip) * gi_constant_info_get_value: (skip)
* @info: a #GIConstantInfo * @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 * Obtain the value associated with the `GIConstantInfo` and store it in the
* @value parameter. @argument needs to be allocated before passing it in. * @value parameter.
* The size of the constant value stored in @argument will be returned. *
* Free the value with gi_constant_info_free_value(). * @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 * Returns: size of the constant, in bytes
* Since: 2.80
*/ */
gsize gsize
gi_constant_info_get_value (GIConstantInfo *info, gi_constant_info_get_value (GIConstantInfo *info,

6
girepository/giconstantinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_CONSTANT_INFO * GI_IS_CONSTANT_INFO:
* @info: an info structure * @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) \ #define GI_IS_CONSTANT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_CONSTANT) (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" #include "gienuminfo.h"
/** /**
* SECTION:gienuminfo * GIEnumInfo:
* @title: GIEnumInfo
* @short_description: Structs representing an enumeration and its values
* *
* A GIEnumInfo represents an enumeration, and a GIValueInfo represents * A `GIEnumInfo` represents an enumeration.
* a value in the 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 * The [class@GIRepository.ValueInfo] for a value is fetched by calling
* a GIEnumInfo. * [method@GIRepository.EnumInfo.get_value] on a `GIEnumInfo`.
*
* Since: 2.80
*/ */
/** /**
@ -53,6 +53,7 @@
* Obtain the number of values this enumeration contains. * Obtain the number of values this enumeration contains.
* *
* Returns: the number of enumeration values * Returns: the number of enumeration values
* Since: 2.80
*/ */
guint guint
gi_enum_info_get_n_values (GIEnumInfo *info) 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 * Obtain the string form of the quark for the error domain associated with
* this enum, if any. * this enum, if any.
* *
* Returns: (transfer none): the string form of the error domain associated * Returns: (transfer none) (nullable): the string form of the error domain
* with this enum, or %NULL. * associated with this enum, or `NULL`.
* Since: 2.80 * Since: 2.80
*/ */
const gchar * const gchar *
@ -103,8 +104,9 @@ gi_enum_info_get_error_domain (GIEnumInfo *info)
* *
* Obtain a value for this enumeration. * Obtain a value for this enumeration.
* *
* Returns: (transfer full): the enumeration value or %NULL if type tag is wrong, * Returns: (transfer full): the enumeration value, free the struct with
* free the struct with gi_base_info_unref() when done. * [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIValueInfo * GIValueInfo *
gi_enum_info_get_value (GIEnumInfo *info, 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. * Obtain an enum type method at index @n.
* *
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling * Returns: (transfer full): the [class@GIRepository.FunctionInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80 * Since: 2.80
*/ */
GIFunctionInfo * 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. * may not match the sign of the type used by the C compiler.
* *
* Returns: the storage type for the enumeration * Returns: the storage type for the enumeration
* Since: 2.80
*/ */
GITypeTag GITypeTag
gi_enum_info_get_storage_type (GIEnumInfo *info) 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; 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: * gi_value_info_get_value:
* @info: a #GIValueInfo * @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 * 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. * return type is to allow both.
* Since: 2.80
*/ */
gint64 gint64
gi_value_info_get_value (GIValueInfo *info) gi_value_info_get_value (GIValueInfo *info)

12
girepository/gienuminfo.h
View File

@ -33,20 +33,24 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_ENUM_INFO * GI_IS_ENUM_INFO:
* @info: an info structure * @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) \ #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_ENUM) || \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FLAGS)) (gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FLAGS))
/** /**
* GI_IS_VALUE_INFO * GI_IS_VALUE_INFO:
* @info: an info structure * @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) \ #define GI_IS_VALUE_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_VALUE) (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 * Returns: (transfer full): the [type@GIRepository.TypeInfo]. Free the struct
* by calling [method@GIRepository.BaseInfo.unref] when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GITypeInfo * GITypeInfo *
gi_field_info_get_type_info (GIFieldInfo *info) 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 * composite type like a nested structure or union even if that is actually
* readable. * readable.
* *
* Returns: true if reading the field succeeded, false otherwise * Returns: `TRUE` if reading the field succeeded, `FALSE` otherwise
* Since: 2.80 * Since: 2.80
*/ */
gboolean 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 * management would by required. A field with a type such as `char *` must be
* set with a setter function. * 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 * Since: 2.80
*/ */
gboolean gboolean

91
girepository/gifunctioninfo.c
View File

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

25
girepository/gifunctioninfo.h
View File

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

99
girepository/giinterfaceinfo.c
View File

@ -33,14 +33,14 @@
#include "giinterfaceinfo.h" #include "giinterfaceinfo.h"
/** /**
* SECTION:giinterfaceinfo * GIInterfaceInfo:
* @title: GIInterfaceInfo
* @short_description: Struct representing a GInterface
* *
* GIInterfaceInfo represents a #GInterface type. * `GIInterfaceInfo` represents a `GInterface` type.
* *
* A GInterface has methods, fields, properties, signals, interfaces, constants, * A `GInterface` has methods, fields, properties, signals,
* virtual functions and prerequisites. * interfaces, constants, virtual functions and prerequisites.
*
* Since: 2.80
*/ */
/** /**
@ -48,10 +48,12 @@
* @info: a #GIInterfaceInfo * @info: a #GIInterfaceInfo
* *
* Obtain the number of prerequisites for this interface type. * 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 * Returns: number of prerequisites
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_prerequisites (GIInterfaceInfo *info) 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: * gi_interface_info_get_prerequisite:
* @info: a #GIInterfaceInfo * @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 * Returns: (transfer full): The prerequisite as a [class@GIRepository.BaseInfo].
* gi_base_info_unref() when done. * Free the struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIBaseInfo * GIBaseInfo *
gi_interface_info_get_prerequisite (GIInterfaceInfo *info, 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. * Obtain the number of properties that this interface type has.
* *
* Returns: number of properties * Returns: number of properties
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_properties (GIInterfaceInfo *info) 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. * Obtain an interface type property at index @n.
* *
* Returns: (transfer full): the #GIPropertyInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.PropertyInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIPropertyInfo * GIPropertyInfo *
gi_interface_info_get_property (GIInterfaceInfo *info, 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. * Obtain the number of methods that this interface type has.
* *
* Returns: number of methods * Returns: number of methods
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_methods (GIInterfaceInfo *info) 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. * Obtain an interface type method at index @n.
* *
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_interface_info_get_method (GIInterfaceInfo *info, gi_interface_info_get_method (GIInterfaceInfo *info,
@ -210,11 +217,14 @@ gi_interface_info_get_method (GIInterfaceInfo *info,
* @info: a #GIInterfaceInfo * @info: a #GIInterfaceInfo
* @name: name of method to obtain * @name: name of method to obtain
* *
* Obtain a method of the interface type given a @name. %NULL will be * Obtain a method of the interface type given a @name.
* returned if there's no method available with that name.
* *
* Returns: (transfer full): the #GIFunctionInfo or %NULL if none found. * `NULL` will be returned if there’s no method available with that name.
* Free the struct by calling gi_base_info_unref() when done. *
* 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 * GIFunctionInfo *
gi_interface_info_find_method (GIInterfaceInfo *info, 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. * Obtain the number of signals that this interface type has.
* *
* Returns: number of signals * Returns: number of signals
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_signals (GIInterfaceInfo *info) 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. * Obtain an interface type signal at index @n.
* *
* Returns: (transfer full): the #GISignalInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.SignalInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GISignalInfo * GISignalInfo *
gi_interface_info_get_signal (GIInterfaceInfo *info, gi_interface_info_get_signal (GIInterfaceInfo *info,
@ -292,12 +304,15 @@ gi_interface_info_get_signal (GIInterfaceInfo *info,
/** /**
* gi_interface_info_find_signal: * gi_interface_info_find_signal:
* @info: a #GIInterfaceInfo * @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` will be returned if there’s no signal available with that name.
* %NULL on failure. *
* 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 * Since: 2.80
*/ */
GISignalInfo * GISignalInfo *
@ -329,6 +344,7 @@ gi_interface_info_find_signal (GIInterfaceInfo *info,
* Obtain the number of virtual functions that this interface type has. * Obtain the number of virtual functions that this interface type has.
* *
* Returns: number of virtual functions * Returns: number of virtual functions
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_vfuncs (GIInterfaceInfo *info) 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. * Obtain an interface type virtual function at index @n.
* *
* Returns: (transfer full): the #GIVFuncInfo. Free the struct by calling * Returns: (transfer full): the [class@GIRepository.VFuncInfo]. Free the struct
* gi_base_info_unref() when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIVFuncInfo * GIVFuncInfo *
gi_interface_info_get_vfunc (GIInterfaceInfo *info, gi_interface_info_get_vfunc (GIInterfaceInfo *info,
@ -385,11 +402,15 @@ gi_interface_info_get_vfunc (GIInterfaceInfo *info,
* @info: a #GIInterfaceInfo * @info: a #GIInterfaceInfo
* @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. See the documentation * Locate a virtual function slot with name @name.
* for gi_object_info_find_vfunc() for more information on virtuals.
* *
* Returns: (transfer full): the #GIVFuncInfo, or %NULL. Free it with * See the documentation for [method@GIRepository.ObjectInfo.find_vfunc] for
* gi_base_info_unref() when done. * 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 * GIVFuncInfo *
gi_interface_info_find_vfunc (GIInterfaceInfo *info, 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. * Obtain the number of constants that this interface type has.
* *
* Returns: number of constants * Returns: number of constants
* Since: 2.80
*/ */
guint guint
gi_interface_info_get_n_constants (GIInterfaceInfo *info) 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. * Obtain an interface type constant at index @n.
* *
* Returns: (transfer full): the #GIConstantInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.ConstantInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIConstantInfo * GIConstantInfo *
gi_interface_info_get_constant (GIInterfaceInfo *info, gi_interface_info_get_constant (GIInterfaceInfo *info,
@ -478,10 +501,12 @@ gi_interface_info_get_constant (GIInterfaceInfo *info,
* gi_interface_info_get_iface_struct: * gi_interface_info_get_iface_struct:
* @info: a #GIInterfaceInfo * @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 * Returns: (transfer full) (nullable): The [class@GIRepository.StructInfo] or
* gi_base_info_unref() when done. * `NULL` if unknown. Free it with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
*/ */
GIStructInfo * GIStructInfo *
gi_interface_info_get_iface_struct (GIInterfaceInfo *info) gi_interface_info_get_iface_struct (GIInterfaceInfo *info)

6
girepository/giinterfaceinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_INTERFACE_INFO * GI_IS_INTERFACE_INFO:
* @info: an info structure * @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) \ #define GI_IS_INTERFACE_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_INTERFACE) (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: * value_to_ffi_type:
* @gvalue: TODO * @gvalue: (transfer none): a [type@GObject.Value] to convert
* @value: TODO * @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 * static ffi_type *
value_to_ffi_type (const GValue *gvalue, gpointer *value) 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: * g_value_to_ffi_return_type:
* @gvalue: TODO * @gvalue: (transfer none): a [type@GObject.Value] to convert
* @ffi_value: TODO * @ffi_value: (transfer none): a [type@GIRepository.Argument] containing the
* @value: TODO * 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 * static ffi_type *
g_value_to_ffi_return_type (const GValue *gvalue, 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: * g_value_from_ffi_value:
* @gvalue: TODO * @gvalue: (inout): a [type@GObject.Value] to set
* @value: TODO * @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 static void
g_value_from_ffi_value (GValue *gvalue, g_value_from_ffi_value (GValue *gvalue,
@ -236,14 +253,19 @@ g_value_from_ffi_value (GValue *gvalue,
/** /**
* gi_cclosure_marshal_generic: (skip) * gi_cclosure_marshal_generic: (skip)
* @closure: TODO * @closure: a [type@GObject.Closure]
* @return_gvalue: TODO * @return_gvalue: (optional) (out caller-allocates): return location for the
* @n_param_values: TODO * return value from the closure, or `NULL` to ignore
* @param_values: TODO * @n_param_values: number of param values
* @invocation_hint: TODO * @param_values: (array length=n_param_values): values to pass to the closure
* @marshal_data: TODO * 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 void
gi_cclosure_marshal_generic (GClosure *closure, gi_cclosure_marshal_generic (GClosure *closure,

278
girepository/giobjectinfo.c
View File

@ -33,20 +33,20 @@
#include "giobjectinfo.h" #include "giobjectinfo.h"
/** /**
* SECTION:giobjectinfo * GIObjectInfo:
* @title: GIObjectInfo
* @short_description: Struct representing a classed type
* *
* GIObjectInfo represents a classed type. * `GIObjectInfo` represents a classed type.
* *
* Classed types in GType inherit from #GTypeInstance; the most common * Classed types in [type@GObject.Type] inherit from
* type is #GObject. * [type@GObject.TypeInstance]; the most common type is [class@GObject.Object].
* *
* A GIObjectInfo doesn't represent a specific instance of a classed type, * A `GIObjectInfo` doesn’t represent a specific instance of a classed type,
* instead this represent the object type (eg class). * 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. * constants and virtual functions.
*
* Since: 2.80
*/ */
/** /**
@ -56,7 +56,8 @@
* *
* Obtain the offset of the specified field. * Obtain the offset of the specified field.
* *
* Returns: field offset in bytes * Returns: field offset, in bytes
* Since: 2.80
*/ */
static gint32 static gint32
gi_object_info_get_field_offset (GIObjectInfo *info, 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. * Obtain the parent of the object type.
* *
* Returns: (transfer full) (nullable): the #GIObjectInfo. Free the struct by calling * Returns: (transfer full) (nullable): The `GIObjectInfo`. Free the struct by
* gi_base_info_unref() when done. * calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIObjectInfo * GIObjectInfo *
gi_object_info_get_parent (GIObjectInfo *info) gi_object_info_get_parent (GIObjectInfo *info)
@ -113,10 +115,11 @@ gi_object_info_get_parent (GIObjectInfo *info)
* gi_object_info_get_abstract: * gi_object_info_get_abstract:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain if the object type is an abstract type, eg if it cannot be * Obtain if the object type is an abstract type, i.e. if it cannot be
* instantiated * instantiated.
* *
* Returns: %TRUE if the object type is abstract * Returns: `TRUE` if the object type is abstract
* Since: 2.80
*/ */
gboolean gboolean
gi_object_info_get_abstract (GIObjectInfo *info) gi_object_info_get_abstract (GIObjectInfo *info)
@ -137,10 +140,9 @@ gi_object_info_get_abstract (GIObjectInfo *info)
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Checks whether the object type is a final type, i.e. if it cannot * Checks whether the object type is a final type, i.e. if it cannot
* be derived * be derived.
*
* Returns: %TRUE if the object type is final
* *
* Returns: `TRUE` if the object type is final
* Since: 2.80 * Since: 2.80
*/ */
gboolean gboolean
@ -162,9 +164,12 @@ gi_object_info_get_final (GIObjectInfo *info)
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain if the object type is of a fundamental type which is not * 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 gboolean
gi_object_info_get_fundamental (GIObjectInfo *info) gi_object_info_get_fundamental (GIObjectInfo *info)
@ -184,9 +189,10 @@ gi_object_info_get_fundamental (GIObjectInfo *info)
* gi_object_info_get_type_name: * gi_object_info_get_type_name:
* @info: a #GIObjectInfo * @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 * const gchar *
gi_object_info_get_type_name (GIObjectInfo *info) 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: * gi_object_info_get_type_init_function_name:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain the function which when called will return the GType * Obtain the name of the function which, when called, will return the
* function for which this object type is registered. * [type@GObject.Type] for this object type.
* *
* Returns: the type init function * Returns: the type init function name
* Since: 2.80
*/ */
const gchar * const gchar *
gi_object_info_get_type_init_function_name (GIObjectInfo *info) 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. * Obtain the number of interfaces that this object type has.
* *
* Returns: number of interfaces * Returns: number of interfaces
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_interfaces (GIObjectInfo *info) 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. * Obtain an object type interface at index @n.
* *
* Returns: (transfer full): the #GIInterfaceInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.InterfaceInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIInterfaceInfo * GIInterfaceInfo *
gi_object_info_get_interface (GIObjectInfo *info, 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. * Obtain the number of fields that this object type has.
* *
* Returns: number of fields * Returns: number of fields
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_fields (GIObjectInfo *info) 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. * Obtain an object type field at index @n.
* *
* Returns: (transfer full): the #GIFieldInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free the struct
* gi_base_info_unref() when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFieldInfo * GIFieldInfo *
gi_object_info_get_field (GIObjectInfo *info, 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. * Obtain the number of properties that this object type has.
* *
* Returns: number of properties * Returns: number of properties
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_properties (GIObjectInfo *info) 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. * Obtain an object type property at index @n.
* *
* Returns: (transfer full): the #GIPropertyInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.PropertyInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIPropertyInfo * GIPropertyInfo *
gi_object_info_get_property (GIObjectInfo *info, 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. * Obtain the number of methods that this object type has.
* *
* Returns: number of methods * Returns: number of methods
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_methods (GIObjectInfo *info) 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. * Obtain an object type method at index @n.
* *
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_object_info_get_method (GIObjectInfo *info, gi_object_info_get_method (GIObjectInfo *info,
@ -440,11 +455,14 @@ gi_object_info_get_method (GIObjectInfo *info,
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* @name: name of method to obtain * @name: name of method to obtain
* *
* Obtain a method of the object type given a @name. %NULL will be * Obtain a method of the object type given a @name.
* returned if there's no method available with that name.
* *
* Returns: (transfer full) (nullable): the #GIFunctionInfo. Free the struct by calling * `NULL` will be returned if there’s no method available with that name.
* gi_base_info_unref() when done. *
* 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 * GIFunctionInfo *
gi_object_info_find_method (GIObjectInfo *info, 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: * gi_object_info_find_method_using_interfaces:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* @name: name of method to obtain * @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 * Obtain a method of the object given a @name, searching both the
* object @info and any interfaces it implements. %NULL will be * object @info and any interfaces it implements.
* returned if there's no method available with that name. *
* `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 * 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 * Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* gi_base_info_unref() when done. * or `NULL` if none was found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_object_info_find_method_using_interfaces (GIObjectInfo *info, 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. * Obtain the number of signals that this object type has.
* *
* Returns: number of signals * Returns: number of signals
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_signals (GIObjectInfo *info) 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. * Obtain an object type signal at index @n.
* *
* Returns: (transfer full): the #GISignalInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.SignalInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GISignalInfo * GISignalInfo *
gi_object_info_get_signal (GIObjectInfo *info, gi_object_info_get_signal (GIObjectInfo *info,
@ -589,11 +614,16 @@ gi_object_info_get_signal (GIObjectInfo *info,
/** /**
* gi_object_info_find_signal: * gi_object_info_find_signal:
* @info: a #GIObjectInfo * @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 * GISignalInfo *
gi_object_info_find_signal (GIObjectInfo *info, 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. * Obtain the number of virtual functions that this object type has.
* *
* Returns: number of virtual functions * Returns: number of virtual functions
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_vfuncs (GIObjectInfo *info) 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. * Obtain an object type virtual function at index @n.
* *
* Returns: (transfer full): the #GIVFuncInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.VFuncInfo]. Free the struct
* gi_base_info_unref() when done. * by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIVFuncInfo * GIVFuncInfo *
gi_object_info_get_vfunc (GIObjectInfo *info, gi_object_info_get_vfunc (GIObjectInfo *info,
@ -681,18 +713,22 @@ gi_object_info_get_vfunc (GIObjectInfo *info,
/** /**
* gi_object_info_find_vfunc: * gi_object_info_find_vfunc:
* @info: a #GIObjectInfo * @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 * Locate a virtual function slot with name @name.
* 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.
* *
* Returns: (transfer full) (nullable): the #GIVFuncInfo, or %NULL. Free it with * Note that the namespace for virtuals is distinct from that of methods; there
* gi_base_info_unref() when done. * 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 * GIVFuncInfo *
gi_object_info_find_vfunc (GIObjectInfo *info, 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: * gi_object_info_find_vfunc_using_interfaces:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* @name: name of vfunc to obtain * @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 * Locate a virtual function slot with name @name, searching both the object
* @info and any interfaces it implements. Note that the namespace for * @info and any interfaces it implements.
* 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 * `NULL` will be returned if there’s no vfunc available with that name.
* retrieved using gi_vfunc_info_get_invoker(), otherwise %NULL will be *
* returned. * 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 * 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 * Returns: (transfer full) (nullable): The [class@GIRepository.VFuncInfo],
* gi_base_info_unref() when done. * or `NULL` if none was found. Free the struct by calling
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIVFuncInfo * GIVFuncInfo *
gi_object_info_find_vfunc_using_interfaces (GIObjectInfo *info, 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. * Obtain the number of constants that this object type has.
* *
* Returns: number of constants * Returns: number of constants
* Since: 2.80
*/ */
guint guint
gi_object_info_get_n_constants (GIObjectInfo *info) 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. * Obtain an object type constant at index @n.
* *
* Returns: (transfer full): the #GIConstantInfo. Free the struct by calling * Returns: (transfer full): The [class@GIRepository.ConstantInfo]. Free the
* gi_base_info_unref() when done. * struct by calling [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIConstantInfo * GIConstantInfo *
gi_object_info_get_constant (GIObjectInfo *info, gi_object_info_get_constant (GIObjectInfo *info,
@ -845,11 +890,13 @@ gi_object_info_get_constant (GIObjectInfo *info,
* gi_object_info_get_class_struct: * gi_object_info_get_class_struct:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Every #GObject has two structures; an instance structure and a class * Every [class@GObject.Object] has two structures; an instance structure and a
* structure. This function returns the metadata for the class structure. * class structure. This function returns the metadata for the class structure.
* *
* Returns: (transfer full) (nullable): the #GIStructInfo or %NULL. Free with * Returns: (transfer full) (nullable): The [class@GIRepository.StructInfo] or
* gi_base_info_unref() when done. * `NULL` if it’s unknown. Free with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
*/ */
GIStructInfo * GIStructInfo *
gi_object_info_get_class_struct (GIObjectInfo *info) gi_object_info_get_class_struct (GIObjectInfo *info)
@ -908,11 +955,16 @@ _get_func(GIObjectInfo *info,
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain the symbol name of the function that should be called to ref this * 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 * object type.
* the symbol is %GIObjectInfoRefFunction, to fetch the function pointer
* see gi_object_info_get_ref_function_name().
* *
* 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 * const char *
gi_object_info_get_ref_function_name (GIObjectInfo *info) 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 * Obtain a pointer to a function which can be used to
* increase the reference count an instance of this object type. * increase the reference count an instance of this object type.
*
* This takes derivation into account and will reversely traverse * This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type. * 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 GIObjectInfoRefFunction
gi_object_info_get_ref_function_pointer (GIObjectInfo *info) 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 * @info: a #GIObjectInfo
* *
* Obtain the symbol name of the function that should be called to unref this * 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 * object type.
* the symbol is %GIObjectInfoUnrefFunction, to fetch the function pointer
* see gi_object_info_get_unref_function_name().
* *
* 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 * const char *
gi_object_info_get_unref_function_name (GIObjectInfo *info) 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 * Obtain a pointer to a function which can be used to
* decrease the reference count an instance of this object type. * decrease the reference count an instance of this object type.
*
* This takes derivation into account and will reversely traverse * This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type. * 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 GIObjectInfoUnrefFunction
gi_object_info_get_unref_function_pointer (GIObjectInfo *info) 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: * gi_object_info_get_set_value_function_name:
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain the symbol name of the function that should be called to convert * Obtain the symbol name of the function that should be called to set a
* set a GValue giving an object instance pointer of this object type. * [type@GObject.Value], given 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().
* *
* 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 * const char *
gi_object_info_get_set_value_function_name (GIObjectInfo *info) 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) * gi_object_info_get_set_value_function_pointer: (skip)
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain a pointer to a function which can be used to * Obtain a pointer to a function which can be used to set a
* set a GValue given an instance of this object type. * [type@GObject.Value], given an instance of this object type.
*
* This takes derivation into account and will reversely traverse * This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type. * 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 GIObjectInfoSetValueFunction
gi_object_info_get_set_value_function_pointer (GIObjectInfo *info) 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 * @info: a #GIObjectInfo
* *
* Obtain the symbol name of the function that should be called to convert * Obtain the symbol name of the function that should be called to convert
* an object instance pointer of this object type to a GValue. * an object instance pointer of this object type to a [type@GObject.Value].
* 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().
* *
* 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 * const char *
gi_object_info_get_get_value_function_name (GIObjectInfo *info) 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) * gi_object_info_get_get_value_function_pointer: (skip)
* @info: a #GIObjectInfo * @info: a #GIObjectInfo
* *
* Obtain a pointer to a function which can be used to * Obtain a pointer to a function which can be used to extract an instance of
* extract an instance of this object type out of a GValue. * this object type out of a [type@GObject.Value].
*
* This takes derivation into account and will reversely traverse * This takes derivation into account and will reversely traverse
* the base classes of this type, starting at the top type. * 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 GIObjectInfoGetValueFunction
gi_object_info_get_get_value_function_pointer (GIObjectInfo *info) 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. * Increases the reference count of an object instance.
* *
* Returns: (transfer full): the object instance * Returns: (transfer full): the object instance
* Since: 2.80
*/ */
typedef void * (*GIObjectInfoRefFunction) (void *object); typedef void * (*GIObjectInfoRefFunction) (void *object);
/** /**
* GIObjectInfoUnrefFunction: (skip) * GIObjectInfoUnrefFunction: (skip)
* @object: object instance pointer * @object: (transfer full): object instance pointer
* *
* Decreases the reference count of an object instance. * Decreases the reference count of an object instance.
*
* Since: 2.80
*/ */
typedef void (*GIObjectInfoUnrefFunction) (void *object); typedef void (*GIObjectInfoUnrefFunction) (void *object);
/** /**
* GIObjectInfoSetValueFunction: (skip) * GIObjectInfoSetValueFunction: (skip)
* @value: a #GValue * @value: a [type@GObject.Value]
* @object: object instance pointer * @object: object instance pointer
* *
* Update @value and attach the object instance pointer @object to it. * Update @value and attach the object instance pointer @object to it.
*
* Since: 2.80
*/ */
typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object); typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
/** /**
* GIObjectInfoGetValueFunction: (skip) * 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 * Returns: (transfer full): the object instance
* Since: 2.80
*/ */
typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value); typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value);
/** /**
* GI_IS_OBJECT_INFO * GI_IS_OBJECT_INFO:
* @info: an info structure * @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) \ #define GI_IS_OBJECT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_OBJECT) (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" #include "gipropertyinfo.h"
/** /**
* SECTION:gipropertyinfo * GIPropertyInfo:
* @title: GIPropertyInfo
* @short_description: Struct representing a property
* *
* 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: * gi_property_info_get_flags:
* @info: a #GIPropertyInfo * @info: a #GIPropertyInfo
* *
* Obtain the flags for this property info. See #GParamFlags for * Obtain the flags for this property info.
* more information about possible flag values. *
* See [type@GObject.ParamFlags] for more information about possible flag
* values.
* *
* Returns: the flags * Returns: the flags
* Since: 2.80
*/ */
GParamFlags GParamFlags
gi_property_info_get_flags (GIPropertyInfo *info) 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. * Obtain the type information for the property @info.
* *
* Returns: (transfer full): the #GITypeInfo, free it with * Returns: (transfer full): The [class@GIRepository.TypeInfo]. Free it with
* gi_base_info_unref() when done. * [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GITypeInfo * GITypeInfo *
gi_property_info_get_type_info (GIPropertyInfo *info) 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: * gi_property_info_get_ownership_transfer:
* @info: a #GIPropertyInfo * @info: a #GIPropertyInfo
* *
* Obtain the ownership transfer for this property. See #GITransfer for more * Obtain the ownership transfer for this property.
* information about transfer values. *
* See [type@GIRepository.Transfer] for more information about transfer values.
* *
* Returns: the transfer * Returns: the transfer
* Since: 2.80
*/ */
GITransfer GITransfer
gi_property_info_get_ownership_transfer (GIPropertyInfo *info) 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: * gi_property_info_get_setter:
* @info: a #GIPropertyInfo * @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 * The setter is only available for `G_PARAM_WRITABLE` properties that
* are also not %G_PARAM_CONSTRUCT_ONLY. * are also not `G_PARAM_CONSTRUCT_ONLY`.
* *
* Returns: (transfer full) (nullable): the function info or %NULL if not set. * Returns: (transfer full) (nullable): The function info, or `NULL` if not set.
* Free it with gi_base_info_unref() when done. * Free it with [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_property_info_get_setter (GIPropertyInfo *info) gi_property_info_get_setter (GIPropertyInfo *info)
@ -174,12 +182,13 @@ gi_property_info_get_setter (GIPropertyInfo *info)
* gi_property_info_get_getter: * gi_property_info_get_getter:
* @info: a #GIPropertyInfo * @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. * Returns: (transfer full) (nullable): The function info, or `NULL` if not set.
* Free it with gi_base_info_unref() when done. * Free it with [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_property_info_get_getter (GIPropertyInfo *info) gi_property_info_get_getter (GIPropertyInfo *info)

6
girepository/gipropertyinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_PROPERTY_INFO * GI_IS_PROPERTY_INFO:
* @info: an info structure * @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) \ #define GI_IS_PROPERTY_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_PROPERTY) (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" #include "giregisteredtypeinfo.h"
/** /**
* SECTION:giregisteredtypeinfo * GIRegisteredTypeInfo:
* @title: GIRegisteredTypeInfo
* @short_description: Struct representing a struct with a GType
* *
* 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, * Could be either a [class@GIRepository.EnumInfo],
* #GIStructInfo or a #GIUnionInfo. * [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. * A registered type info struct has a name and a type function.
* *
* To get the name call gi_registered_type_info_get_type_name(). * To get the name call [method@GIRepository.RegisteredTypeInfo.get_type_name].
* Most users want to call gi_registered_type_info_get_g_type() and don't worry * Most users want to call [method@GIRepository.RegisteredTypeInfo.get_g_type]
* about the rest of the details. * and don’t worry about the rest of the details.
*
* Since: 2.80
*/ */
/** /**
@ -56,9 +58,12 @@
* @info: a #GIRegisteredTypeInfo * @info: a #GIRegisteredTypeInfo
* *
* Obtain the type name of the struct within the GObject type system. * 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 * const gchar *
gi_registered_type_info_get_type_name (GIRegisteredTypeInfo *info) 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: * gi_registered_type_info_get_type_init_function_name:
* @info: a #GIRegisteredTypeInfo * @info: a #GIRegisteredTypeInfo
* *
* Obtain the type init function for @info. The type init function is the * Obtain the type init function for @info.
* 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.
* *
* Returns: the symbol name of the type init function, suitable for * The type init function is the function which will register the
* passing into g_module_symbol(). * [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 * const gchar *
gi_registered_type_info_get_type_init_function_name (GIRegisteredTypeInfo *info) 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: * gi_registered_type_info_get_g_type:
* @info: a #GIRegisteredTypeInfo * @info: a #GIRegisteredTypeInfo
* *
* Obtain the #GType for this registered type or G_TYPE_NONE which a special meaning. * Obtain the [type@GObject.Type] for this registered type.
* 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.
* *
* 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 GType
gi_registered_type_info_get_g_type (GIRegisteredTypeInfo *info) gi_registered_type_info_get_g_type (GIRegisteredTypeInfo *info)

7
girepository/giregisteredtypeinfo.h
View File

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

95
girepository/girffi.c
View File

@ -35,14 +35,6 @@
#include "girepository.h" #include "girepository.h"
#include "girepository-private.h" #include "girepository-private.h"
/**
* SECTION:girffi
* @short_description: TODO
* @title: girffi
*
* TODO
*/
static ffi_type * static ffi_type *
gi_type_tag_get_ffi_type_internal (GITypeTag tag, gi_type_tag_get_ffi_type_internal (GITypeTag tag,
gboolean is_pointer, gboolean is_pointer,
@ -115,12 +107,14 @@ gi_type_tag_get_ffi_type_internal (GITypeTag tag,
/** /**
* gi_type_tag_get_ffi_type: * gi_type_tag_get_ffi_type:
* @type_tag: A #GITypeTag * @type_tag: a #GITypeTag
* @is_pointer: Whether or not this is a pointer type * @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 * ffi_type *
gi_type_tag_get_ffi_type (GITypeTag type_tag, 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: * 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 * ffi_type *
gi_type_info_get_ffi_type (GITypeInfo *info) 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: * gi_callable_info_get_ffi_arg_types:
* @callable_info: a callable info from a typelib * @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 * Returns: (transfer container) (array length=n_args_p): an array of
* should be freed using g_free() after use. * `ffi_type*`. The array itself should be freed using [func@GLib.free] after
* use.
* Since: 2.80
*/ */
static ffi_type ** static ffi_type **
gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info, 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: * gi_callable_info_get_ffi_return_type:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* *
* Fetches the ffi_type for a corresponding return value of * Fetches the `ffi_type` for a corresponding return value of
* a #GICallableInfo * 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 * static ffi_type *
gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info) 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: * gi_function_info_prep_invoker:
* @info: A #GIFunctionInfo * @info: A #GIFunctionInfo
* @invoker: Output invoker structure * @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError * @error: A #GError
* *
* Initialize the caller-allocated @invoker structure with a cache * Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to * 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 * A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure * by a language binding could contain a [type@GIRepository.FunctionInvoker]
* inside the binding's function mapping. * 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 gboolean
gi_function_info_prep_invoker (GIFunctionInfo *info, gi_function_info_prep_invoker (GIFunctionInfo *info,
@ -300,18 +300,19 @@ gi_function_info_prep_invoker (GIFunctionInfo *info,
* gi_function_invoker_new_for_address: * gi_function_invoker_new_for_address:
* @addr: The address * @addr: The address
* @info: A #GICallableInfo * @info: A #GICallableInfo
* @invoker: Output invoker structure * @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError * @error: A #GError
* *
* Initialize the caller-allocated @invoker structure with a cache * Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to * 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 * A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure * by a language binding could contain a [type@GIRepository.FunctionInvoker]
* inside the binding's function mapping. * 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 gboolean
gi_function_invoker_new_for_address (gpointer addr, gi_function_invoker_new_for_address (gpointer addr,
@ -336,11 +337,14 @@ gi_function_invoker_new_for_address (gpointer addr,
/** /**
* gi_function_invoker_destroy: * gi_function_invoker_destroy:
* @invoker: A #GIFunctionInvoker * @invoker: (transfer none): A #GIFunctionInvoker
* *
* Release all resources allocated for the internals of @invoker; callers * Release all resources allocated for the internals of @invoker.
* are responsible for freeing any resources allocated for the structure *
* Callers are responsible for freeing any resources allocated for the structure
* itself however. * itself however.
*
* Since: 2.80
*/ */
void void
gi_function_invoker_destroy (GIFunctionInvoker *invoker) gi_function_invoker_destroy (GIFunctionInvoker *invoker)
@ -357,14 +361,16 @@ typedef struct {
/** /**
* gi_callable_info_create_closure: * gi_callable_info_create_closure:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* @cif: a ffi_cif structure * @cif: a `ffi_cif` structure
* @callback: the ffi callback * @callback: the ffi callback
* @user_data: data to be passed into the callback * @user_data: data to be passed into the callback
* *
* Prepares a callback for ffi invocation. * Prepares a callback for ffi invocation.
* *
* Returns: the ffi_closure or NULL on error. The return value * Returns: (transfer full) (nullable): the `ffi_closure`, or `NULL` on error.
* should be freed by calling gi_callable_info_destroy_closure(). * The return value should be freed by calling
* [method@GIRepository.CallableInfo.destroy_closure].
* Since: 2.80
*/ */
ffi_closure * ffi_closure *
gi_callable_info_create_closure (GICallableInfo *callable_info, 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 * @callable_info: a callable info from a typelib
* @closure: ffi closure * @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 * gpointer *
gi_callable_info_get_closure_native_address (GICallableInfo *callable_info, 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: * gi_callable_info_destroy_closure:
* @callable_info: a callable info from a typelib * @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 void
gi_callable_info_destroy_closure (GICallableInfo *callable_info, gi_callable_info_destroy_closure (GICallableInfo *callable_info,

40
girepository/girffi.h
View File

@ -34,38 +34,48 @@ G_BEGIN_DECLS
/** /**
* GIFFIClosureCallback: * GIFFIClosureCallback:
* @Param1: TODO * @cif: the `ffi_cif` passed to
* @Param2: TODO * [method@GIRepository.CallableInfo.create_closure]
* @Param3: TODO * @ret: (out caller-allocates): a pointer to the memory used for the function’s
* @Param4: TODO * 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 *, typedef void (*GIFFIClosureCallback) (ffi_cif *cif,
void *, void *ret,
void **, void **args,
void *); void *user_data);
/** /**
* GIFunctionInvoker: * GIFunctionInvoker:
* @cif: the cif * @cif: the cif
* @native_address: the native address * @native_address: the native address
* *
* TODO * Structure containing the data necessary to invoke a callable function.
*
* Since: 2.80
*/ */
typedef struct _GIFunctionInvoker GIFunctionInvoker; typedef struct {
struct _GIFunctionInvoker {
ffi_cif cif; ffi_cif cif;
gpointer native_address; gpointer native_address;
/*< private >*/ /*< private >*/
gpointer padding[3]; gpointer padding[3];
}; } GIFunctionInvoker;
/** /**
* GIFFIReturnValue: * GIFFIReturnValue:
* *
* TODO * The type of a return value from a callable invocation closure.
*
* Since: 2.80
*/ */
typedef GIArgument GIFFIReturnValue; typedef GIArgument GIFFIReturnValue;

2
girepository/girmodule.c
View File

@ -93,6 +93,8 @@ gi_ir_module_free (GIIrModule *module)
* @args: Remaining arguments * @args: Remaining arguments
* *
* Report a fatal error, then exit. * Report a fatal error, then exit.
*
* Since: 2.80
*/ */
void void
gi_ir_module_fatal (GIIrTypelibBuild *build, 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 * 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 * offsets have been computed, and also computes the overall size and
* alignment for the type. * alignment for the type.
*
* Since: 2.80
*/ */
void void
gi_ir_node_compute_offsets (GIIrTypelibBuild *build, 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: * gi_ir_parser_parse_string:
* @parser: a #GIIrParser * @parser: a #GIIrParser
* @namespace: the namespace of the string * @namespace: the namespace of the string
* @filename: (allow-none): Path to parsed file, or %NULL * @filename: (nullable) (type filename): Path to parsed file, or `NULL`
* @buffer: the data containing the XML * @buffer: (array length=length): the data containing the XML
* @length: length of the data * @length: length of the data, in bytes
* @error: return location for a #GError, or %NULL * @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 * 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 * GIIrModule *
gi_ir_parser_parse_string (GIIrParser *parser, gi_ir_parser_parse_string (GIIrParser *parser,
@ -3757,14 +3759,17 @@ gi_ir_parser_parse_string (GIIrParser *parser,
/** /**
* gi_ir_parser_parse_file: * gi_ir_parser_parse_file:
* @parser: a #GIIrParser * @parser: a #GIIrParser
* @filename: filename to parse * @filename: (type filename): filename to parse
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Parse GIR XML file, and return a list of a a #GirModule for each * Parse the given GIR XML file, and return a list of a
* &lt;namespace/&gt; element within the file. * [class@GIRepository.IrModule] for each `<namespace/>` element within the
* file.
* *
* Returns: (transfer container): a newly allocated list of #GIIrModule. The modules themselves * Returns: (transfer container): a newly allocated list of
* are owned by the #GIIrParser and will be freed along with the parser. * [class@GIRepository.IrModule]s. The modules themselves
* are owned by the `GIIrParser` and will be freed along with the parser.
* Since: 2.80
*/ */
GIIrModule * GIIrModule *
gi_ir_parser_parse_file (GIIrParser *parser, 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: * gi_ir_writer_write:
* @filename: filename to write to * @filename: (type filename): filename to write to
* @ns: GIR namespace to write * @ns: GIR namespace to write
* @needs_prefix: if the filename needs prefixing * @needs_prefix: if the filename needs prefixing
* @show_all: if field size calculations should be included * @show_all: if field size calculations should be included
* *
* Writes the output of a typelib represented by @ns * Writes the output of a typelib represented by @ns
* into a GIR xml file named @filename. * into a GIR xml file named @filename.
*
* Since: 2.80
*/ */
void void
gi_ir_writer_write (const char *filename, gi_ir_writer_write (const char *filename,

41
girepository/gisignalinfo.c
View File

@ -33,27 +33,30 @@
#include "gisignalinfo.h" #include "gisignalinfo.h"
/** /**
* SECTION:gisignalinfo * GISignalInfo:
* @title: GISignalInfo
* @short_description: Struct representing a signal
* *
* GISignalInfo represents a signal. * `GISignalInfo` represents a signal.
* *
* It's a sub-struct of #GICallableInfo and contains a set of flags and * It’s a sub-struct of [class@GIRepository.CallableInfo] and contains a set of
* a class closure. * flags and a class closure.
* *
* See #GICallableInfo for information on how to retreive arguments * See [class@GIRepository.CallableInfo] for information on how to retrieve
* and other metadata from the signal. * arguments and other metadata from the signal.
*
* Since: 2.80
*/ */
/** /**
* gi_signal_info_get_flags: * gi_signal_info_get_flags:
* @info: a #GISignalInfo * @info: a #GISignalInfo
* *
* Obtain the flags for this signal info. See #GSignalFlags for * Obtain the flags for this signal info.
* more information about possible flag values. *
* See [flags@GObject.SignalFlags] for more information about possible flag
* values.
* *
* Returns: the flags * Returns: the flags
* Since: 2.80
*/ */
GSignalFlags GSignalFlags
gi_signal_info_get_flags (GISignalInfo *info) gi_signal_info_get_flags (GISignalInfo *info)
@ -96,11 +99,14 @@ gi_signal_info_get_flags (GISignalInfo *info)
* gi_signal_info_get_class_closure: * gi_signal_info_get_class_closure:
* @info: a #GISignalInfo * @info: a #GISignalInfo
* *
* Obtain the class closure for this signal if one is set. The class * Obtain the class closure for this signal if one is set.
* 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): 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 * GIVFuncInfo *
gi_signal_info_get_class_closure (GISignalInfo *info) 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: * gi_signal_info_true_stops_emit:
* @info: a #GISignalInfo * @info: a #GISignalInfo
* *
* Obtain if the returning true in the signal handler will * Obtain if the returning `TRUE` in the signal handler will stop the emission
* stop the emission of the signal. * 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 gboolean
gi_signal_info_true_stops_emit (GISignalInfo *info) gi_signal_info_true_stops_emit (GISignalInfo *info)

6
girepository/gisignalinfo.h
View File

@ -34,10 +34,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_SIGNAL_INFO * GI_IS_SIGNAL_INFO:
* @info: an info structure * @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) \ #define GI_IS_SIGNAL_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_SIGNAL) (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" #include "gistructinfo.h"
/** /**
* SECTION:gistructinfo * GIStructInfo:
* @title: GIStructInfo
* @short_description: Struct representing a C structure
* *
* GIStructInfo represents a generic C structure type. * `GIStructInfo` represents a generic C structure type.
* *
* A structure has methods and fields. * A structure has methods and fields.
*
* Since: 2.80
*/ */
/** /**
@ -51,6 +51,7 @@
* Obtain the number of fields this structure has. * Obtain the number of fields this structure has.
* *
* Returns: number of fields * Returns: number of fields
* Since: 2.80
*/ */
guint guint
gi_struct_info_get_n_fields (GIStructInfo *info) 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. * Obtain the offset of the specified field.
* *
* Returns: field offset in bytes * Returns: field offset, in bytes
* Since: 2.80
*/ */
static gint32 static gint32
gi_struct_get_field_offset (GIStructInfo *info, 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. * Obtain the type information for field with specified index.
* *
* Returns: (transfer full): the #GIFieldInfo, free it with gi_base_info_unref() * Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free it with
* when done. * [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFieldInfo * GIFieldInfo *
gi_struct_info_get_field (GIStructInfo *info, 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. * 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 * Since: 2.80
* Returns: (transfer full): the #GIFieldInfo or %NULL if not found,
* free it with gi_base_info_unref() when done.
*/ */
GIFieldInfo * GIFieldInfo *
gi_struct_info_find_field (GIStructInfo *info, 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. * Obtain the number of methods this structure has.
* *
* Returns: number of methods * Returns: number of methods
* Since: 2.80
*/ */
guint guint
gi_struct_info_get_n_methods (GIStructInfo *info) 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. * Obtain the type information for method with specified index.
* *
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref() * Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free it with
* when done. * [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_struct_info_get_method (GIStructInfo *info, 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. * Obtain the type information for method named @name.
* *
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref() * Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* when done. * or `NULL` if none was found. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/ */
GIFunctionInfo * GIFunctionInfo *
gi_struct_info_find_method (GIStructInfo *info, 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. * 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 gsize
gi_struct_info_get_size (GIStructInfo *info) 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. * Obtain the required alignment of the structure.
* *
* Returns: required alignment in bytes * Returns: required alignment, in bytes
* Since: 2.80
*/ */
gsize gsize
gi_struct_info_get_alignment (GIStructInfo *info) gi_struct_info_get_alignment (GIStructInfo *info)
@ -251,11 +261,13 @@ gi_struct_info_get_alignment (GIStructInfo *info)
/** /**
* gi_struct_info_is_foreign: * 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 gboolean
gi_struct_info_is_foreign (GIStructInfo *info) gi_struct_info_is_foreign (GIStructInfo *info)
@ -270,11 +282,14 @@ gi_struct_info_is_foreign (GIStructInfo *info)
* gi_struct_info_is_gtype_struct: * gi_struct_info_is_gtype_struct:
* @info: a #GIStructInfo * @info: a #GIStructInfo
* *
* Return true if this structure represents the "class structure" for some * 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 * [class@GObject.Object] or `GInterface`.
* from generated public APIs.
* *
* 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 gboolean
gi_struct_info_is_gtype_struct (GIStructInfo *info) 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. * 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 * Since: 2.80
*/ */
const char * 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. * 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 * Since: 2.80
*/ */
const char * const char *

6
girepository/gistructinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_STRUCT_INFO * GI_IS_STRUCT_INFO:
* @info: an info structure * @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) \ #define GI_IS_STRUCT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_STRUCT) (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 * (i.e. only if the type of the C function’s formal parameter is a pointer to a
* pointer). * pointer).
* *
* Returns: true if it is a pointer * Returns: `TRUE` if it is a pointer
* Since: 2.80 * Since: 2.80
*/ */
gboolean gboolean
@ -128,9 +128,10 @@ gi_type_info_get_tag (GITypeInfo *info)
* @info: a #GITypeInfo * @info: a #GITypeInfo
* @n: index of the parameter * @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 * Since: 2.80
*/ */
GITypeInfo * 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 * 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 * and boxed values, this function returns full information about the referenced
* type. You can then inspect the type of the returned * type.
* [class@GIRepository.BaseInfo] to further query whether it is a concrete *
* [class@GObject.Object], an interface, a structure, etc., using * 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]. * [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. * `NULL`. Free it with gi_base_info_unref() when done.
* Since: 2.80
*/ */
GIBaseInfo * GIBaseInfo *
gi_type_info_get_interface (GITypeInfo *info) gi_type_info_get_interface (GITypeInfo *info)
@ -230,9 +234,11 @@ gi_type_info_get_interface (GITypeInfo *info)
* @info: a #GITypeInfo * @info: a #GITypeInfo
* *
* Obtain the position of the argument which gives the array length of the type. * 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. * 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 * Returns: the array length argument index, or `-1` if the type is not an array
* or it has no length argument
* Since: 2.80 * Since: 2.80
*/ */
gint gint
@ -264,10 +270,11 @@ gi_type_info_get_array_length_index (GITypeInfo *info)
* gi_type_info_get_array_fixed_size: * gi_type_info_get_array_fixed_size:
* @info: a #GITypeInfo * @info: a #GITypeInfo
* *
* Obtain the fixed array size of the type. The type tag must be a * Obtain the fixed array size of the type, in number of elements (not bytes).
* `GI_TYPE_TAG_ARRAY` or `-1` will be returned.
* *
* 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 * Since: 2.80
*/ */
gssize gssize
@ -299,10 +306,11 @@ gi_type_info_get_array_fixed_size (GITypeInfo *info)
* gi_type_info_is_zero_terminated: * gi_type_info_is_zero_terminated:
* @info: a #GITypeInfo * @info: a #GITypeInfo
* *
* Obtain if the last element of the array is `NULL`. The type tag must be a * Obtain if the last element of the array is `NULL`.
* `GI_TYPE_TAG_ARRAY` or false will be returned.
* *
* 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 * Since: 2.80
*/ */
gboolean gboolean
@ -395,7 +403,11 @@ gi_type_info_get_storage_type (GITypeInfo *info)
* @storage_type: a [type@GIRepository.TypeTag] obtained from * @storage_type: a [type@GIRepository.TypeTag] obtained from
* [method@GIRepository.TypeInfo.get_storage_type] * [method@GIRepository.TypeInfo.get_storage_type]
* @hash_pointer: a pointer, such as a [struct@GLib.HashTable] data pointer * @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 * GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers. * [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: * gi_type_info_argument_from_hash_pointer:
* @info: a #GITypeInfo * @info: a #GITypeInfo
* @hash_pointer: a pointer, such as a [struct@GLib.HashTable] data pointer * @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 * GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers. * [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: * gi_type_tag_hash_pointer_from_argument:
* @storage_type: a [type@GIRepository.TypeTag] obtained from * @storage_type: a [type@GIRepository.TypeTag] obtained from
* [method@GIRepository.TypeInfo.get_storage_type] * [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 * GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers. * [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: * gi_type_info_hash_pointer_from_argument:
* @info: a #GITypeInfo * @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 * GLib data structures, such as [type@GLib.List], [type@GLib.SList], and
* [type@GLib.HashTable], all store data pointers. * [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 * @short_description: Layout and accessors for typelib
* @stability: Stable * @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. * containing reflective information about a GObject library.
* *
* What the typelib describes and the types used are the same for every * 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: * The typelib has the following general format:
* *
* |[<!-- language="C" --> * ```
* typelib ::= header, section-index, directory, blobs, attributes, attributedata * typelib ::= header, section-index, directory, blobs, attributes, attributedata
* *
* directory ::= list of entries * directory ::= list of entries
@ -69,13 +69,15 @@ G_BEGIN_DECLS
* blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
* attribute ::= offset, key, value * attribute ::= offset, key, value
* attributedata ::= string data for attributes * attributedata ::= string data for attributes
* ]| * ```
* *
* Details * ## Details
* *
* We describe the fragments that make up the typelib in the form of C structs * 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 * (although some fall short of being valid C structs since they contain
* multiple flexible arrays). * multiple flexible arrays).
*
* Since: 2.80
*/ */
/* /*
@ -148,8 +150,11 @@ Changes since 0.1:
/** /**
* GI_IR_MAGIC: * GI_IR_MAGIC:
* *
* Identifying prefix for the typelib. This was inspired by XPCOM, * Identifying prefix for the typelib.
* which in turn borrowed from PNG. *
* This was inspired by XPCOM, which in turn borrowed from PNG.
*
* Since: 2.80
*/ */
#define GI_IR_MAGIC "GOBJ\nMETADATA\r\n\032" #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 * The integral value of this enumeration appears in each "Blob" component of
* a typelib to identify its type. * a typelib to identify its type.
*
* Since: 2.80
*/ */
typedef enum { typedef enum {
BLOB_TYPE_INVALID, 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 * 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. * collection of meta-information, such as the number of entries and dependencies.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
gchar magic[16]; gchar magic[16];
@ -327,6 +336,8 @@ typedef struct {
* @GI_SECTION_DIRECTORY_INDEX: TODO * @GI_SECTION_DIRECTORY_INDEX: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef enum { typedef enum {
GI_SECTION_END = 0, GI_SECTION_END = 0,
@ -342,6 +353,8 @@ typedef enum {
* and may or may not be present in the typelib. Presently, just used * and may or may not be present in the typelib. Presently, just used
* for the directory index. This allows a form of dynamic extensibility * for the directory index. This allows a form of dynamic extensibility
* with different tradeoffs from the format minor version. * with different tradeoffs from the format minor version.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 id; guint32 id;
@ -363,6 +376,8 @@ typedef struct {
* *
* All blobs pointed to by a directory entry start with the same layout for * 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) * the first 8 bytes (the reserved flags may be used by some blob types)
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -382,6 +397,8 @@ typedef struct {
* @tag: A #GITypeTag * @tag: A #GITypeTag
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint reserved : 8; guint reserved : 8;
@ -419,6 +436,8 @@ union _SimpleTypeBlob
* In this case, the integer is actually an offset into the directory (see * 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 * above). Because the header is larger than 2^8=256 bits, all offsets will
* have one of the upper 24 bits set. * have one of the upper 24 bits set.
*
* Since: 2.80
*/ */
typedef union _SimpleTypeBlob SimpleTypeBlob; 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, * 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 * the low byte describes a basic type, otherwise the 32bit number is an
* offset which points to a TypeBlob. * offset which points to a TypeBlob.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -511,6 +532,8 @@ typedef struct {
* @arguments: An array of ArgBlob for the arguments of the function. * @arguments: An array of ArgBlob for the arguments of the function.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
SimpleTypeBlob return_type; SimpleTypeBlob return_type;
@ -539,6 +562,8 @@ typedef struct {
* #CallbackBlob, #SignalBlob. * #CallbackBlob, #SignalBlob.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 1 */ guint16 blob_type; /* 1 */
@ -576,6 +601,8 @@ typedef struct {
* @reserved2: Reserved for future use. * @reserved2: Reserved for future use.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 1 */ guint16 blob_type; /* 1 */
@ -610,6 +637,8 @@ typedef struct {
* the return value type. * the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 2 */ guint16 blob_type; /* 2 */
@ -629,6 +658,8 @@ typedef struct {
* @interface: Index of the directory entry for the interface. * @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. * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -644,6 +675,8 @@ typedef struct {
* @size: TODO * @size: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef union { typedef union {
guint16 length; guint16 length;
@ -669,6 +702,8 @@ typedef union {
* @type: TODO * @type: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 pointer :1; guint16 pointer :1;
@ -696,6 +731,8 @@ typedef struct {
* @type: Describes the type of the list elements. * @type: Describes the type of the list elements.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -718,6 +755,8 @@ typedef struct {
* @domains: TODO * @domains: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -739,6 +778,8 @@ typedef struct {
* @value: The numerical value * @value: The numerical value
* *
* Values commonly occur in enums and flags. * Values commonly occur in enums and flags.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 deprecated : 1; guint32 deprecated : 1;
@ -763,6 +804,8 @@ typedef struct {
* @type: The type of the field. * @type: The type of the field.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -792,6 +835,8 @@ typedef struct {
* type. * type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -827,6 +872,8 @@ typedef struct {
* the contents of this struct type * the contents of this struct type
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -876,6 +923,8 @@ typedef struct {
* @discriminator_type: Type of the discriminator * @discriminator_type: Type of the discriminator
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -918,6 +967,8 @@ typedef struct {
* @values: TODO * @values: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -966,6 +1017,8 @@ typedef struct {
* @type: Describes the type of the property. * @type: Describes the type of the property.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -1007,6 +1060,8 @@ typedef struct {
* and the return value type. * and the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 deprecated : 1; guint16 deprecated : 1;
@ -1056,6 +1111,8 @@ typedef struct {
* the return value type. * the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -1116,6 +1173,8 @@ typedef struct {
* interfaces. * interfaces.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 7 */ guint16 blob_type; /* 7 */
@ -1176,6 +1235,8 @@ typedef struct {
* interfaces. * interfaces.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -1215,6 +1276,8 @@ typedef struct {
* @reserved2: Reserved for future use. * @reserved2: Reserved for future use.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -1239,6 +1302,8 @@ typedef struct {
* @value: The value of the attribute (also a string) * @value: The value of the attribute (also a string)
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 offset; guint32 offset;
@ -1283,6 +1348,7 @@ void gi_typelib_check_sanity (void);
* TODO * TODO
* *
* Returns: TODO * Returns: TODO
* Since: 2.80
*/ */
#define gi_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)]) #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 * @GI_TYPELIB_ERROR_INVALID_BLOB: a typelib blob is invalid
* *
* A error set while validating the #GITypelib * A error set while validating the #GITypelib
*
* Since: 2.80
*/ */
typedef enum typedef enum
{ {
@ -1310,6 +1378,8 @@ typedef enum
* GI_TYPELIB_ERROR: * GI_TYPELIB_ERROR:
* *
* TODO * TODO
*
* Since: 2.80
*/ */
#define GI_TYPELIB_ERROR (gi_typelib_error_quark ()) #define GI_TYPELIB_ERROR (gi_typelib_error_quark ())
@ -1329,6 +1399,8 @@ AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info,
* GITypelibHashBuilder: * GITypelibHashBuilder:
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct _GITypelibHashBuilder GITypelibHashBuilder; typedef struct _GITypelibHashBuilder GITypelibHashBuilder;

103
girepository/gitypelib.c
View File

@ -145,12 +145,13 @@ get_type_blob (GITypelib *typelib,
/** /**
* gi_typelib_get_dir_entry: * gi_typelib_get_dir_entry:
* @typelib: TODO * @typelib: a #GITypelib
* @index: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry (GITypelib *typelib, gi_typelib_get_dir_entry (GITypelib *typelib,
@ -183,12 +184,14 @@ get_section_by_id (GITypelib *typelib,
/** /**
* gi_typelib_get_dir_entry_by_name: * gi_typelib_get_dir_entry_by_name:
* @typelib: TODO * @typelib: a #GITypelib
* @name: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_name (GITypelib *typelib, 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: * gi_typelib_get_dir_entry_by_gtype_name:
* @typelib: TODO * @typelib: a #GITypelib
* @gtype_name: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib, 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: * gi_typelib_matches_gtype_name_prefix:
* @typelib: TODO * @typelib: a #GITypelib
* @gtype_name: TODO * @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 gboolean
gi_typelib_matches_gtype_name_prefix (GITypelib *typelib, 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: * gi_typelib_get_dir_entry_by_error_domain:
* @typelib: TODO * @typelib: a #GITypelib
* @error_domain: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, 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: * gi_typelib_check_sanity:
* *
* TODO * Check compile-time sizes of various typelib file format types are as
* expected.
*
* Since: 2.80
*/ */
void void
gi_typelib_check_sanity (void) gi_typelib_check_sanity (void)
@ -2180,12 +2194,14 @@ prefix_with_context (GError **error,
/** /**
* gi_typelib_validate: * gi_typelib_validate:
* @typelib: TODO * @typelib: a #GITypelib
* @error: TODO * @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 gboolean
gi_typelib_validate (GITypelib *typelib, gi_typelib_validate (GITypelib *typelib,
@ -2219,9 +2235,10 @@ gi_typelib_validate (GITypelib *typelib,
/** /**
* gi_typelib_error_quark: * 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 GQuark
gi_typelib_error_quark (void) gi_typelib_error_quark (void)
@ -2240,15 +2257,17 @@ static GSList *library_paths;
* *
* Prepends @directory to the search path that is used to * Prepends @directory to the search path that is used to
* search shared libraries referenced by imported namespaces. * search shared libraries referenced by imported namespaces.
*
* Multiple calls to this function all contribute to the final * Multiple calls to this function all contribute to the final
* list of paths. * list of paths.
* The list of paths is unique and shared for all #GIRepository *
* instances across the process, but it doesn't affect namespaces * The list of paths is unique and shared for all
* imported before the call. * [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 * If the library is not found in the directories configured
* in this way, loading will fall back to the system library * 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. * See the documentation of your dynamic linker for full details.
* *
* Since: 2.80 * Since: 2.80
@ -2379,15 +2398,15 @@ gi_typelib_ensure_open (GITypelib *typelib)
/** /**
* gi_typelib_new_from_memory: (skip) * gi_typelib_new_from_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib * @memory: (array length=len): address of memory chunk containing the typelib
* @len: length of memory chunk containing the typelib * @len: length of memory chunk containing the typelib, in bytes
* @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.
* *
* The memory block pointed to by @typelib will be automatically freed when the * The memory block pointed to by @typelib will be automatically freed when the
* repository is destroyed. * repository is destroyed.
* *
* Returns: (transfer full): the new #GITypelib * Returns: (transfer full): the new [type@GIRepository.Typelib]
* Since: 2.80 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2413,11 +2432,11 @@ gi_typelib_new_from_memory (guint8 *memory,
* gi_typelib_new_from_const_memory: (skip) * gi_typelib_new_from_const_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib * @memory: (array length=len): address of memory chunk containing the typelib
* @len: length 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 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2445,9 +2464,9 @@ gi_typelib_new_from_const_memory (const guchar *memory,
* the repository is destroyed * the repository is destroyed
* @error: a #GError * @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 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2474,7 +2493,7 @@ gi_typelib_new_from_mapped_file (GMappedFile *mfile,
* gi_typelib_free: * gi_typelib_free:
* @typelib: (transfer full): a #GITypelib * @typelib: (transfer full): a #GITypelib
* *
* Free a `GITypelib`. * Free a [type@GIRepository.Typelib].
* *
* Since: 2.80 * Since: 2.80
*/ */
@ -2518,7 +2537,7 @@ gi_typelib_get_namespace (GITypelib *typelib)
* *
* Loads a symbol from a `GITypelib`. * Loads a symbol from a `GITypelib`.
* *
* Returns: true on success * Returns: `TRUE` on success
* Since: 2.80 * Since: 2.80
*/ */
gboolean gboolean

234
girepository/gitypes.h
View File

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

14
girepository/giunioninfo.c
View File

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

8
girepository/giunresolvedinfo.c
View File

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

6
girepository/giunresolvedinfo.h
View File

@ -32,10 +32,12 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/** /**
* GI_IS_UNRESOLVED_INFO * GI_IS_UNRESOLVED_INFO:
* @info: an info structure * @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) \ #define GI_IS_UNRESOLVED_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_UNRESOLVED) (gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_UNRESOLVED)

51
girepository/givfuncinfo.c
View File

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