## gs-plugin-job-refine

gs-plugin-job-refine — A plugin job to refine GsApps and add more data

## Functions

GsPluginJob * | gs_plugin_job_refine_new_for_app ()
GsPluginJob * | gs_plugin_job_refine_new ()
GsAppList * | gs_plugin_job_refine_get_result_list ()

## Types and Values

#define | GS_TYPE_PLUGIN_JOB_REFINE
| GsPluginJobRefine

## Description

GsPluginJobRefine is a GsPluginJob representing a refine operation.

It’s used to query and add more data to a set of GsApps. The data to be set is controlled by the GsPluginRefineFlags, and is looked up for all the apps in a GsAppList by the loaded plugins.

This class is a wrapper around GsPluginClass.refine_async, calling it for all loaded plugins, with some additional refinements done on the results.

In particular, if an app in the GsAppList has `GS_APP_QUIRK_IS_WILDCARD`, refining it will replace it with zero or more non-wildcard GsApps in the GsAppList, all of which are candidates for what the wildcard represents. For example, they may have the same ID as the wildcard, or match its name. Refining is the canonical process for resolving wildcards.

This means that the GsAppList at the end of the refine operation may not match the GsAppList passed in as input. Retrieve the final GsAppList using `gs_plugin_job_refine_get_result_list()`. The GsAppList which was passed into the job will not be modified.

Internally, the `GsPluginClass.refine_async()` functions are called on all the plugins in series, and in series with calls to `gs_odrs_provider_refine_async()` and `gs_rewrite_resources_async()`. Once all of those calls are finished, zero or more recursive calls to `run_refine_internal_async()` are made in parallel to do a similar refine process on the addons, runtime and related components for all the components in the input GsAppList. The refine job is complete once all these recursive calls complete.

The call to `gs_rewrite_resources_async()` will rewrite the CSS of apps to refer to locally cached resources, rather than HTTP/HTTPS URIs for images (for example).

FIXME: Ideally, the `GsPluginClass.refine_async()` calls would happen in parallel, but this cannot be the case until the results of the `refine_async()` call in one plugin don’t depend on the results of `refine_async()` in another. This still happens with several pairs of plugins.

``run_async()` | v /-----------------------+-------------+----------------+------------------------------\ | | | | | plugin->`refine_async()` | | | | v plugin->`refine_async()` | | | | v … | | | | v `gs_odrs_provider_refine_async()` | | | | v `gs_rewrite_resources_async()` | | | | v | | | | | \-----------------------+-------------+----------------+------------------------------/ | `finish_refine_internal_op()` | v /----------------------------+-----------------\ | | | `run_refine_internal_async()` `run_refine_internal_async()` … | | | v v v \----------------------------+-----------------/ | `finish_refine_internal_recursion()``

See also: GsPluginClass.refine_async

## Functions

### gs_plugin_job_refine_new_for_app ()

    GsPluginJob *
    gs_plugin_job_refine_new_for_app (GsApp *app,
                                      GsPluginRefineFlags flags);

Create a new GsPluginJobRefine for refining the given `app` .

#### Parameters

app | the GsApp to refine |
flags | flags to affect what is refined |

#### Returns

a new GsPluginJobRefine.

[transfer full]

Since: 42

### gs_plugin_job_refine_new ()

    GsPluginJob *
    gs_plugin_job_refine_new (GsAppList *app_list,
                              GsPluginRefineFlags flags);

Create a new GsPluginJobRefine for refining the given `app_list` .

#### Parameters

app_list | the list of GsApps to refine |
flags | flags to affect what is refined |

#### Returns

a new GsPluginJobRefine.

[transfer full]

Since: 42

### gs_plugin_job_refine_get_result_list ()

    GsAppList *
    gs_plugin_job_refine_get_result_list (GsPluginJobRefine *self);

Get the full list of refined GsApps. This includes apps created in place of wildcards, if wildcards were provided in the GsAppList passed to `gs_plugin_job_refine_new()`.

If this is called before the job is complete, `NULL` will be returned.

#### Parameters

self | a GsPluginJobRefine |

#### Returns

the job results, or `NULL` on error or if called before the job has completed.

[transfer none][nullable]

Since: 42

## Types and Values

### GS_TYPE_PLUGIN_JOB_REFINE

    #define GS_TYPE_PLUGIN_JOB_REFINE (gs_plugin_job_refine_get_type ())

### GsPluginJobRefine

    typedef struct _GsPluginJobRefine GsPluginJobRefine;