## Metered Data Utilities

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

gboolean | gs_metered_block_on_download_scheduler ()
void | gs_metered_block_on_download_scheduler_async ()
gboolean | gs_metered_block_on_download_scheduler_finish ()
gboolean | gs_metered_remove_from_download_scheduler ()
void | gs_metered_remove_from_download_scheduler_async ()
gboolean | gs_metered_remove_from_download_scheduler_finish ()
GVariant * | gs_metered_build_scheduler_parameters_for_app ()
gboolean | gs_metered_block_app_list_on_download_scheduler ()

## 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