girffi: libgirepository API Reference

## girffi girffi — TODO |

## Functions

void | (*GIFFIClosureCallback) ()
ffi_type * | gi_type_tag_get_ffi_type ()
void | gi_type_tag_extract_ffi_return_value ()
ffi_type * | g_type_info_get_ffi_type ()
void | gi_type_info_extract_ffi_return_value ()
void | g_type_info_argument_from_hash_pointer ()
GITypeTag | g_type_info_get_storage_type ()
gpointer | g_type_info_hash_pointer_from_argument ()
gboolean | g_function_info_prep_invoker ()
gboolean | g_function_invoker_new_for_address ()
void | g_function_invoker_destroy ()
ffi_closure * | g_callable_info_prepare_closure ()
void | g_callable_info_free_closure ()

## Types and Values

struct | GIFunctionInvoker
typedef | GIFFIReturnValue

## Description

TODO

## Functions

### GIFFIClosureCallback ()

    void
    (*GIFFIClosureCallback) (ffi_cif *Param1,
                             void *Param2,
                             void **Param3,
                             void *Param4);

TODO

#### Parameters

Param1 | TODO |
Param2 | TODO |
Param3 | TODO |
Param4 | TODO |

### gi_type_tag_get_ffi_type ()

    ffi_type *
    gi_type_tag_get_ffi_type (GITypeTag type_tag,
                              gboolean is_pointer);

TODO

#### Parameters

type_tag | A GITypeTag |
is_pointer | Whether or not this is a pointer type |

#### Returns

A ffi_type corresponding to the platform default C ABI for `tag` and `is_pointer` .

### gi_type_tag_extract_ffi_return_value ()

    void
    gi_type_tag_extract_ffi_return_value (GITypeTag return_tag,
                                          GIInfoType interface_type,
                                          GIFFIReturnValue *ffi_value,
                                          GIArgument *arg);

Extract the correct bits from an `ffi_arg` return value into GIArgument.

See: https://bugzilla.gnome.org/show_bug.cgi?id=665152

Also see `ffi_call(3)`: the storage requirements for return values are "special".

The `interface_type` argument only applies if `return_tag` is `GI_TYPE_TAG_INTERFACE`. Otherwise it is ignored.

#### Parameters

return_tag | GITypeTag of the return value |
interface_type | GIInfoType of the underlying interface type |
ffi_value | pointer to GIFFIReturnValue union containing the return value from ``ffi_call()`` |
arg | pointer to an allocated GIArgument. | [out caller-allocates]

Since: 1.72

### g_type_info_get_ffi_type ()

    ffi_type *
    g_type_info_get_ffi_type (GITypeInfo *info);

TODO

#### Parameters

info | A GITypeInfo |

#### Returns

A ffi_type corresponding to the platform default C ABI for `info` .

### gi_type_info_extract_ffi_return_value ()

    void
    gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
                                           GIFFIReturnValue *ffi_value,
                                           GIArgument *arg);

Extract the correct bits from an `ffi_arg` return value into GIArgument.

See: https://bugzilla.gnome.org/show_bug.cgi?id=665152

Also see `ffi_call(3)`: the storage requirements for return values are "special".

#### Parameters

return_info | GITypeInfo describing the return type |
ffi_value | pointer to GIFFIReturnValue union containing the return value from ``ffi_call()`` |
arg | pointer to an allocated GIArgument. | [out caller-allocates]

### g_type_info_argument_from_hash_pointer ()

    void
    g_type_info_argument_from_hash_pointer
                                   (GITypeInfo *info,
                                    gpointer hash_pointer,
                                    GIArgument *arg);

GLib data structures, such as GList, GSList, and GHashTable, all store data pointers. In the case where the list or hash table is storing single types rather than structs, these data pointers may have values stuffed into them via macros such as `GPOINTER_TO_INT`.

Use this function to ensure that all values are correctly extracted from stuffed pointers, regardless of the machine's architecture or endianness.

This function fills in the appropriate field of `arg` with the value extracted from `hash_pointer` , depending on the storage type of `info` .

#### Parameters

info | a GITypeInfo |
hash_pointer | A pointer, such as a GHashTable data pointer |
arg | A GIArgument to fill in |

Since: 1.66

### g_type_info_get_storage_type ()

    GITypeTag
    g_type_info_get_storage_type (GITypeInfo *info);

Obtain the type tag corresponding to the underlying storage type in C for the type. See GITypeTag for a list of type tags.

#### Parameters

info | a GITypeInfo |

#### Returns

the type tag

Since: 1.66

### g_type_info_hash_pointer_from_argument ()

    gpointer
    g_type_info_hash_pointer_from_argument
                                   (GITypeInfo *info,
                                    GIArgument *arg);

GLib data structures, such as GList, GSList, and GHashTable, all store data pointers. In the case where the list or hash table is storing single types rather than structs, these data pointers may have values stuffed into them via macros such as `GPOINTER_TO_INT`.

Use this function to ensure that all values are correctly stuffed into pointers, regardless of the machine's architecture or endianness.

This function returns a pointer stuffed with the appropriate field of `arg` , depending on the storage type of `info` .

#### Parameters

info | a GITypeInfo |
arg | A GIArgument with the value to stuff into a pointer |

#### Returns

A stuffed pointer, that can be stored in a GHashTable, for example

Since: 1.66

### g_function_info_prep_invoker ()

    gboolean
    g_function_info_prep_invoker (GIFunctionInfo *info,
                                  GIFunctionInvoker *invoker,
                                  GError **error);

Initialize the caller-allocated `invoker` structure with a cache of information needed to invoke the C function corresponding to `info` with the platform's default ABI.

A primary intent of this function is that a dynamic structure allocated by a language binding could contain a GIFunctionInvoker structure inside the binding's function mapping.

#### Parameters

info | A GIFunctionInfo |
invoker | Output invoker structure |
error | A GError |

#### Returns

`TRUE` on success, `FALSE` otherwise with `error` set.

### g_function_invoker_new_for_address ()

    gboolean
    g_function_invoker_new_for_address (gpointer addr,
                                        GICallableInfo *info,
                                        GIFunctionInvoker *invoker,
                                        GError **error);

Initialize the caller-allocated `invoker` structure with a cache of information needed to invoke the C function corresponding to `info` with the platform's default ABI.

A primary intent of this function is that a dynamic structure allocated by a language binding could contain a GIFunctionInvoker structure inside the binding's function mapping.

#### Parameters

addr | The address |
info | A GICallableInfo |
invoker | Output invoker structure |
error | A GError |

#### Returns

`TRUE` on success, `FALSE` otherwise with `error` set.

### g_function_invoker_destroy ()

    void
    g_function_invoker_destroy (GIFunctionInvoker *invoker);

Release all resources allocated for the internals of `invoker` ; callers are responsible for freeing any resources allocated for the structure itself however.

#### Parameters

invoker | A GIFunctionInvoker |

### g_callable_info_prepare_closure ()

    ffi_closure *
    g_callable_info_prepare_closure (GICallableInfo *callable_info,
                                     ffi_cif *cif,
                                     GIFFIClosureCallback callback,
                                     gpointer user_data);

`g_callable_info_prepare_closure` has been deprecated since version 1.72 and should not be used in newly-written code.

Use `g_callable_info_create_closure()` instead

Prepares a callback for ffi invocation.

#### Parameters

callable_info | a callable info from a typelib |
cif | a ffi_cif structure |
callback | the ffi callback |
user_data | data to be passed into the callback |

#### Returns

the native address of the closure or `NULL` on error. The return value should be freed by calling `g_callable_info_free_closure()`.

### g_callable_info_free_closure ()

    void
    g_callable_info_free_closure (GICallableInfo *callable_info,
                                  ffi_closure *closure);

`g_callable_info_free_closure` has been deprecated since version 1.72 and should not be used in newly-written code.

Use `g_callable_info_destroy_closure()` instead, in conjunction with `g_callable_info_create_closure()`.

Should free a ffi_closure returned from `g_callable_info_prepare_closure()`, which may cause a segfault because the native address is returned instead of the closure address. May do nothing and leak memory instead of freeing to avoid segfaults.

#### Parameters

callable_info | a callable info from a typelib |
closure | ffi closure |

## Types and Values

### struct GIFunctionInvoker

    struct GIFunctionInvoker {
      ffi_cif cif;
      gpointer native_address;
    };

TODO

#### Members

ffi_cif `cif`; | the cif |
gpointer `native_address`; | the native address |

### GIFFIReturnValue

    typedef GIArgument GIFFIReturnValue;

TODO