luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-25 21:46:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

giobjectinfo: Port documentation to gi-docgen and update

Browse Source 
Review and update the documentation, making sure it’s complete,
formatted in gi-docgen format, and has all appropriate GIR annotations
and `Since:` lines.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
This commit is contained in:
Philip Withnall 2023-12-13 13:23:44 +00:00
parent 2ebaa439e5
commit 5422788455
2 changed files with 190 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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)