AscCompose: AppStream Compose Library Reference Manual

## AscCompose

AscCompose — Compose collection metadata easily.

## Functions

void | (*AscCheckMetadataEarlyFn) ()
GPtrArray * | (*AscTranslateDesktopTextFn) ()
AscCompose * | asc_compose_new ()
void | asc_compose_reset ()
void | asc_compose_add_unit ()
void | asc_compose_add_allowed_cid ()
const gchar * | asc_compose_get_prefix ()
void | asc_compose_set_prefix ()
const gchar * | asc_compose_get_origin ()
void | asc_compose_set_origin ()
AsFormatKind | asc_compose_get_format ()
void | asc_compose_set_format ()
const gchar * | asc_compose_get_media_baseurl ()
void | asc_compose_set_media_baseurl ()
AscComposeFlags | asc_compose_get_flags ()
void | asc_compose_set_flags ()
void | asc_compose_add_flags ()
void | asc_compose_remove_flags ()
AscIconPolicy * | asc_compose_get_icon_policy ()
void | asc_compose_set_icon_policy ()
const gchar * | asc_compose_get_cainfo ()
void | asc_compose_set_cainfo ()
const gchar * | asc_compose_get_data_result_dir ()
void | asc_compose_set_data_result_dir ()
const gchar * | asc_compose_get_icons_result_dir ()
void | asc_compose_set_icons_result_dir ()
const gchar * | asc_compose_get_media_result_dir ()
void | asc_compose_set_media_result_dir ()
const gchar * | asc_compose_get_hints_result_dir ()
void | asc_compose_set_hints_result_dir ()
void | asc_compose_remove_custom_allowed ()
void | asc_compose_add_custom_allowed ()
gssize | asc_compose_get_max_screenshot_size ()
void | asc_compose_set_max_screenshot_size ()
void | asc_compose_set_check_metadata_early_func ()
void | asc_compose_set_desktop_entry_l10n_func ()
AscUnit * | asc_compose_get_locale_unit ()
void | asc_compose_set_locale_unit ()
GPtrArray * | asc_compose_get_results ()
GPtrArray * | asc_compose_fetch_components ()
gboolean | asc_compose_has_errors ()
GPtrArray * | asc_compose_run ()
void | asc_compose_finalize_results ()
void | asc_compose_finalize_result ()

## Types and Values

#define | ASC_TYPE_COMPOSE
struct | AscComposeClass
enum | AscComposeFlags
| AscCompose

## Includes

    #include <appstream-compose.h>

## Description

## Functions

### AscCheckMetadataEarlyFn ()

    void
    (*AscCheckMetadataEarlyFn) (AscResult *cres,
                                const AscUnit *unit,
                                gpointer user_data);

Function which is called after all metainfo and related data (e.g. desktop-entry files) has been loaded, but *before* any expensive operations such as screenshot downloads or font searches are performed.

This function can be useful to filter out unwanted components early in the process and avoid unneeded downloads and other data processing. By the time this function is called, the component's global ID should be finalized and should not change any longer.

Please note that this function may be called from any thread, and thread safety needs to be taked care off by the callee.

#### Parameters

cres | A pointer to generated AscResult. | [not nullable]
unit | The unit we are currently processing. | [not nullable]
user_data | Additional data. |

### AscTranslateDesktopTextFn ()

    GPtrArray *
    (*AscTranslateDesktopTextFn) (const GKeyFile *de,
                                  const gchar *text,
                                  gpointer user_data);

Function which is called while parsing a desktop-entry file to allow external translations of string values. This is used in e.g. the Ubuntu distribution.

The return value must contain a list of strings with the locale name in even indices, and the text translated to the preceding locale in the following odd indices.

#### Parameters

de | A pointer to the desktop-entry data we are reading. | [not nullable]
text | The string to translate. |
user_data | Additional data. |

#### Returns

A new GPtrArray containing the translation mapping.

[not nullable][transfer full]

### asc_compose_new ()

    AscCompose *
    asc_compose_new (void);

Creates a new AscCompose.

### asc_compose_reset ()

    void
    asc_compose_reset (AscCompose *compose);

Reset the results, units and run-specific settings so the instance can be reused for another metadata generation run.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_add_unit ()

    void
    asc_compose_add_unit (AscCompose *compose,
                          AscUnit *unit);

Add an AscUnit as data source for metadata processing.

#### Parameters

compose | an AscCompose instance. |
unit | The AscUnit to add |

### asc_compose_add_allowed_cid ()

    void
    asc_compose_add_allowed_cid (AscCompose *compose,
                                 const gchar *component_id);

Adds a component ID to the allowlist. If the list is not empty, only components in the list will be added to the metadata output.

#### Parameters

compose | an AscCompose instance. |
component_id | The component-id to whitelist |

### asc_compose_get_prefix ()

    const gchar *
    asc_compose_get_prefix (AscCompose *compose);

Get the directory prefix used for processing.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_prefix ()

    void
    asc_compose_set_prefix (AscCompose *compose,
                            const gchar *prefix);

Set the directory prefix the to-be-processed units are using.

#### Parameters

compose | an AscCompose instance. |
prefix | a directory prefix, e.g. "/usr" |

### asc_compose_get_origin ()

    const gchar *
    asc_compose_get_origin (AscCompose *compose);

Get the metadata origin field.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_origin ()

    void
    asc_compose_set_origin (AscCompose *compose,
                            const gchar *origin);

Set the metadata origin field (e.g. "debian" or "flathub")

#### Parameters

compose | an AscCompose instance. |
origin | the origin. |

### asc_compose_get_format ()

    AsFormatKind
    asc_compose_get_format (AscCompose *compose);

get the format type we are generating.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_format ()

    void
    asc_compose_set_format (AscCompose *compose,
                            AsFormatKind kind);

Set the format kind of the collection metadata that we should generate.

#### Parameters

compose | an AscCompose instance. |
kind | The format, e.g. `AS_FORMAT_KIND_XML` |

### asc_compose_get_media_baseurl ()

    const gchar *
    asc_compose_get_media_baseurl (AscCompose *compose);

Get the media base URL to be used for the generated data, or `NULL` if this feature is not used.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_media_baseurl ()

    void
    asc_compose_set_media_baseurl (AscCompose *compose,
                                   const gchar *url);

Set the media base URL for the generated metadata. Can be `NULL`.

#### Parameters

compose | an AscCompose instance. |
url | the media base URL. | [nullable]

### asc_compose_get_flags ()

    AscComposeFlags
    asc_compose_get_flags (AscCompose *compose);

Get the flags controlling compose behavior.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_flags ()

    void
    asc_compose_set_flags (AscCompose *compose,
                           AscComposeFlags flags);

Set compose flags bitfield that controls the enabled features for this AscCompose.

#### Parameters

compose | an AscCompose instance. |
flags | The compose flags bitfield. |

### asc_compose_add_flags ()

    void
    asc_compose_add_flags (AscCompose *compose,
                           AscComposeFlags flags);

Add compose flags.

#### Parameters

compose | an AscCompose instance. |
flags | The compose flags to add. |

### asc_compose_remove_flags ()

    void
    asc_compose_remove_flags (AscCompose *compose,
                              AscComposeFlags flags);

Remove compose flags.

#### Parameters

compose | an AscCompose instance. |
flags | The compose flags to remove. |

### asc_compose_get_icon_policy ()

    AscIconPolicy *
    asc_compose_get_icon_policy (AscCompose *compose);

Get the policy for how icons should be distributed to any AppStream clients.

#### Parameters

compose | an AscCompose instance. |

#### Returns

an AscIconPolicy.

[transfer none]

### asc_compose_set_icon_policy ()

    void
    asc_compose_set_icon_policy (AscCompose *compose,
                                 AscIconPolicy *policy);

Set an icon policy object, overriding the existing one.

#### Parameters

compose | an AscCompose instance. |
policy | an AscIconPolicy instance. | [not nullable]

### asc_compose_get_cainfo ()

    const gchar *
    asc_compose_get_cainfo (AscCompose *compose);

Get the CA file used to verify peers with, or `NULL` for default.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_cainfo ()

    void
    asc_compose_set_cainfo (AscCompose *compose,
                            const gchar *cainfo);

Set a CA file holding one or more certificates to verify peers with for download operations performed by this AscCompose.

#### Parameters

compose | an AscCompose instance. |
cainfo | a valid file path |

### asc_compose_get_data_result_dir ()

    const gchar *
    asc_compose_get_data_result_dir (AscCompose *compose);

Get the data result directory.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_data_result_dir ()

    void
    asc_compose_set_data_result_dir (AscCompose *compose,
                                     const gchar *dir);

Set an output location where generated metadata should be saved. If this is set to `NULL`, no metadata will be saved.

#### Parameters

compose | an AscCompose instance. |
dir | the metadata save location. |

### asc_compose_get_icons_result_dir ()

    const gchar *
    asc_compose_get_icons_result_dir (AscCompose *compose);

Get the icon result directory.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_icons_result_dir ()

    void
    asc_compose_set_icons_result_dir (AscCompose *compose,
                                      const gchar *dir);

Set an output location where plain icons for the processed metadata are stored.

#### Parameters

compose | an AscCompose instance. |
dir | the icon storage location. |

### asc_compose_get_media_result_dir ()

    const gchar *
    asc_compose_get_media_result_dir (AscCompose *compose);

Get the media result directory, that can be served on a webserver.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_media_result_dir ()

    void
    asc_compose_set_media_result_dir (AscCompose *compose,
                                      const gchar *dir);

Set an output location to store media (screenshots, icons, ...) that will be served on a webserver via the URL set as media baseurl.

#### Parameters

compose | an AscCompose instance. |
dir | the media storage location. |

### asc_compose_get_hints_result_dir ()

    const gchar *
    asc_compose_get_hints_result_dir (AscCompose *compose);

Get hints report output directory.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_hints_result_dir ()

    void
    asc_compose_set_hints_result_dir (AscCompose *compose,
                                      const gchar *dir);

Set an output location for HTML reports of issues generated during a compose run.

#### Parameters

compose | an AscCompose instance. |
dir | the hints data directory. |

### asc_compose_remove_custom_allowed ()

    void
    asc_compose_remove_custom_allowed (AscCompose *compose,
                                       const gchar *key_id);

Remove a key from the allowlist used to filter the `<custom/>` tag entries.

#### Parameters

compose | an AscCompose instance. |
key_id | the custom key to drop from the allowed list. |

### asc_compose_add_custom_allowed ()

    void
    asc_compose_add_custom_allowed (AscCompose *compose,
                                    const gchar *key_id);

Add a key to the allowlist that is used to filter custom tag values.

#### Parameters

compose | an AscCompose instance. |
key_id | the custom key to add to the allowed list. |

### asc_compose_get_max_screenshot_size ()

    gssize
    asc_compose_get_max_screenshot_size (AscCompose *compose);

Get the maximum size a screenshot video or image can have. A size < 0 may be returned for no limit, setting a limit of 0 will disable screenshots.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_max_screenshot_size ()

    void
    asc_compose_set_max_screenshot_size (AscCompose *compose,
                                         gssize size_bytes);

Set the maximum size a screenshot video or image can have. A size < 0 may be set to allow unlimited sizes, setting a limit of 0 will disable screenshot caching entirely.

#### Parameters

compose | an AscCompose instance. |
size_bytes | maximum size of a screenshot image or video in bytes |

### asc_compose_set_check_metadata_early_func ()

    void
    asc_compose_set_check_metadata_early_func
                                   (AscCompose *compose,
                                    AscCheckMetadataEarlyFn func,
                                    gpointer user_data);

Set an custom callback to be run when most of the metadata has been loaded, but no expensive operations (like downloads or icon rendering) have been done yet. This can be used to ignore unwanted components early on.

The callback function may be called from any thread, so it needs to ensure thread safety on its own.

#### Parameters

compose | an AscCompose instance. |
func | the AscCheckMetainfoLoadResultFn function to be called. | [scope notified]
user_data | user data for `func` |

### asc_compose_set_desktop_entry_l10n_func ()

    void
    asc_compose_set_desktop_entry_l10n_func
                                   (AscCompose *compose,
                                    AscTranslateDesktopTextFn func,
                                    gpointer user_data);

Set a custom desktop-entry field localization functions to be run for specialized desktop-entry localization schemes such as used in Ubuntu.

The callback function may be called from any thread, so it needs to ensure thread safety on its own.

#### Parameters

compose | an AscCompose instance. |
func | the AscTranslateDesktopTextFn function to be called. | [scope notified]
user_data | user data for `func` |

### asc_compose_get_locale_unit ()

    AscUnit *
    asc_compose_get_locale_unit (AscCompose *compose);

Get the unit we use for locale processing

Return: (transfer none) (nullable): The unit used for locale processing, or `NULL` for default.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_set_locale_unit ()

    void
    asc_compose_set_locale_unit (AscCompose *compose,
                                 AscUnit *locale_unit);

Set a specific unit that is used for fetching locale information. This may be useful in case a special language pack layout is used, but is generally not necessary to be set explicitly, as locale will be found in the unit where the metadata is by default.

#### Parameters

compose | an AscCompose instance. |
locale_unit | the unit used for locale processing. |

### asc_compose_get_results ()

    GPtrArray *
    asc_compose_get_results (AscCompose *compose);

Get the results of the last processing run.

#### Parameters

compose | an AscCompose instance. |

#### Returns

The results.

[transfer none][element-type AscResult]

### asc_compose_fetch_components ()

    GPtrArray *
    asc_compose_fetch_components (AscCompose *compose);

Get the results components extracted in the last data processing run.

#### Parameters

compose | an AscCompose instance. |

#### Returns

The components.

[transfer container][element-type AsComponent]

### asc_compose_has_errors ()

    gboolean
    asc_compose_has_errors (AscCompose *compose);

Check if the last run generated any errors (which will cause metadata to be ignored).

#### Parameters

compose | an AscCompose instance. |

#### Returns

`TRUE` if we had errors.

### asc_compose_run ()

    GPtrArray *
    asc_compose_run (AscCompose *compose,
                     GCancellable *cancellable,
                     GError **error);

Process the registered units and generate collection metadata from found components.

#### Parameters

compose | an AscCompose instance. |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

The results, or `NULL` on error.

[transfer none][element-type AscResult]

### asc_compose_finalize_results ()

    void
    asc_compose_finalize_results (AscCompose *compose);

Perform final validation of generated data. Calling this function is not necessary, unless the final check was explicitly disabled using the `ASC_COMPOSE_FLAG_NO_FINAL_CHECK` flag.

#### Parameters

compose | an AscCompose instance. |

### asc_compose_finalize_result ()

    void
    asc_compose_finalize_result (AscCompose *compose,
                                 AscResult *result);

Perform final validation of generated data for the specified result container.

#### Parameters

compose | an AscCompose instance. |
result | the AscResult to finalize |

## Types and Values

### ASC_TYPE_COMPOSE

    #define ASC_TYPE_COMPOSE (asc_compose_get_type ())

### struct AscComposeClass

    struct AscComposeClass {
    	GObjectClass parent_class;
    };

### enum AscComposeFlags

#### Members

ASC_COMPOSE_FLAG_NONE |  |
ASC_COMPOSE_FLAG_USE_THREADS |  |
ASC_COMPOSE_FLAG_ALLOW_NET |  |
ASC_COMPOSE_FLAG_VALIDATE |  |
ASC_COMPOSE_FLAG_STORE_SCREENSHOTS |  |
ASC_COMPOSE_FLAG_ALLOW_SCREENCASTS |  |
ASC_COMPOSE_FLAG_PROCESS_FONTS |  |
ASC_COMPOSE_FLAG_PROCESS_TRANSLATIONS |  |
ASC_COMPOSE_FLAG_IGNORE_ICONS |  |
ASC_COMPOSE_FLAG_PROCESS_UNPAIRED_DESKTOP |  |
ASC_COMPOSE_FLAG_PROPAGATE_CUSTOM |  |
ASC_COMPOSE_FLAG_PROPAGATE_ARTIFACTS |  |
ASC_COMPOSE_FLAG_NO_FINAL_CHECK |  |

### AscCompose

    typedef struct _AscCompose AscCompose;