Metered Data Utilities

Metered Data Utilities — Utility functions to help with metered data handling

Stability Level

Unstable, unless otherwise indicated

Functions

Includes

#include <gnome-software.h>

Description

Metered data handling is provided by Mogwai, which implements a download scheduler to control when, and in which order, large downloads happen on the system.

All large downloads from GsPlugin.update_apps_async() calls should be scheduled using Mogwai, which will notify gnome-software when those downloads can start and stop, according to system policy.

The functions in this file make interacting with the scheduling daemon a little simpler. Since all GsPlugin method calls happen in worker threads, typically without a GMainContext, all interaction with the scheduler should be blocking. libmogwai-schedule-client was designed to be asynchronous; so these helpers make it synchronous.

Functions

gs_metered_block_on_download_scheduler ()

gboolean
gs_metered_block_on_download_scheduler
                               (GVariant *parameters,
                                gpointer *schedule_entry_handle_out,
                                GCancellable *cancellable,
                                GError **error);

Create a schedule entry with the given parameters , and block until permission is given to download.

FIXME: This will currently ignore later revocations of that download permission, and does not support creating a schedule entry per app. The schedule entry must later be removed from the schedule by passing the handle from schedule_entry_handle_out to gs_metered_remove_from_download_scheduler(), otherwise resources will leak. This is an opaque handle and should not be inspected.

If a schedule entry cannot be created, or if cancellable is cancelled, an error will be set and FALSE returned.

The keys understood by parameters are listed in the documentation for mwsc_scheduler_schedule_async().

This function will likely be called from a GsPluginLoader worker thread.

Parameters

parameters

a GVariant of type a{sv} specifying parameters for the schedule entry, or NULL to pass no parameters.

[nullable]

schedule_entry_handle_out

return location for a handle to the resulting schedule entry.

[out][not optional]

cancellable

a GCancellable, or NULL.

[nullable]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 3.38


gs_metered_block_on_download_scheduler_async ()

void
gs_metered_block_on_download_scheduler_async
                               (GVariant *parameters,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronous version of gs_metered_block_on_download_scheduler().

Parameters

parameters

a GVariant of type a{sv} specifying parameters for the schedule entry, or NULL to pass no parameters.

[nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

callback to call when the operation is finished

 

user_data

data to pass to callback

 

Since: 44


gs_metered_block_on_download_scheduler_finish ()

gboolean
gs_metered_block_on_download_scheduler_finish
                               (GAsyncResult *result,
                                gpointer *schedule_entry_handle_out,
                                GError **error);

Finish function for gs_metered_block_on_download_scheduler_async().

See gs_metered_block_on_download_scheduler().

Parameters

result

result of the async operation

 

schedule_entry_handle_out

return location for a handle to the resulting schedule entry.

[out][not optional]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 44


gs_metered_remove_from_download_scheduler ()

gboolean
gs_metered_remove_from_download_scheduler
                               (gpointer schedule_entry_handle,
                                GCancellable *cancellable,
                                GError **error);

Remove a schedule entry previously created by gs_metered_block_on_download_scheduler(). This must be called after gs_metered_block_on_download_scheduler() has successfully returned, or resources will leak. It should be called once the corresponding download is complete.

Parameters

schedule_entry_handle

schedule entry handle as returned by gs_metered_block_on_download_scheduler().

[transfer full][nullable]

cancellable

a GCancellable, or NULL.

[nullable]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 3.38


gs_metered_remove_from_download_scheduler_async ()

void
gs_metered_remove_from_download_scheduler_async
                               (gpointer schedule_entry_handle,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronous version of gs_metered_remove_from_download_scheduler().

Parameters

schedule_entry_handle

schedule entry handle as returned by gs_metered_block_on_download_scheduler().

[transfer full][nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

callback to call when the operation is finished

 

user_data

data to pass to callback

 

Since: 44


gs_metered_remove_from_download_scheduler_finish ()

gboolean
gs_metered_remove_from_download_scheduler_finish
                               (gpointer schedule_entry_handle,
                                GAsyncResult *result,
                                GError **error);

Finish an asynchronous remove operation started with gs_metered_remove_from_download_scheduler_async().

Parameters

schedule_entry_handle

schedule entry handle as returned by gs_metered_block_on_download_scheduler() result: result of the async operation.

[transfer full][nullable]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 44


gs_metered_build_scheduler_parameters_for_app ()

GVariant *
gs_metered_build_scheduler_parameters_for_app
                               (GsApp *app);

Build a GVariant of scheduler parameters for downloading app .

This is suitable to pass to gs_metered_block_on_download_scheduler() or gs_metered_block_on_download_scheduler_async().

Parameters

app

a GsApp to get the scheduler parameters from

 

Returns

scheduler parameters for app .

[transfer floating][not nullable]

Since: 44


gs_metered_block_app_list_on_download_scheduler ()

gboolean
gs_metered_block_app_list_on_download_scheduler
                               (GsAppList *app_list,
                                gpointer *schedule_entry_handle_out,
                                GCancellable *cancellable,
                                GError **error);

Version of gs_metered_block_on_download_scheduler() which extracts the download parameters from the apps in the given app_list .

Parameters

app_list

a GsAppList to get the scheduler parameters from

 

schedule_entry_handle_out

return location for a handle to the resulting schedule entry.

[out][not optional]

cancellable

a GCancellable, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 3.38