gs-download-utils: GNOME Software Reference Manual

## gs-download-utils gs-download-utils — Download and HTTP utilities |

## Functions

SoupSession * | gs_build_soup_session ()
void | (*GsDownloadProgressCallback) ()
GQuark | gs_download_error_quark ()
void | gs_download_stream_async ()
gboolean | gs_download_stream_finish ()
void | gs_download_file_async ()
gboolean | gs_download_file_finish ()

## Types and Values

enum | GsDownloadError
#define | GS_DOWNLOAD_ERROR

## Description

A set of utilities for downloading things and doing HTTP requests.

## Functions

### gs_build_soup_session ()

    SoupSession *
    gs_build_soup_session (void);

Build a new SoupSession configured with the gnome-software user agent.

A new SoupSession should be used for each independent download context, such as in different plugins. Each SoupSession caches HTTP connections and authentication information, and these likely needn’t be shared between plugins. Using separate sessions reduces thread contention.

#### Returns

a new SoupSession.

[transfer full]

Since: 42

### GsDownloadProgressCallback ()

    void
    (*GsDownloadProgressCallback) (gsize bytes_downloaded,
                                   gsize total_download_size,
                                   gpointer user_data);

A progress callback to indicate how far a download has progressed.

`total_download_size` may be zero (for example, at the start of the download), so implementations of this callback must be careful to avoid division by zero errors.

`total_download_size` is guaranteed to always be greater than or equal to `bytes_downloaded` .

#### Parameters

bytes_downloaded | number of bytes downloaded so far |
total_download_size | the total size of the download, in bytes |
user_data | data passed to the calling function |

Since: 42

### gs_download_error_quark ()

    GQuark
    gs_download_error_quark (void);

### gs_download_stream_async ()

    void
    gs_download_stream_async (SoupSession *soup_session,
                              const gchar *uri,
                              GOutputStream *output_stream,
                              const gchar *last_etag,
                              GDateTime *last_modified_date,
                              int io_priority,
                              GsDownloadProgressCallback progress_callback,
                              gpointer progress_user_data,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Download `uri` and write it to `output_stream` asynchronously.

If `last_etag` is non-`NULL` or `last_modified_date` is non-`NULL`, they will be sent to the server, which may return a ‘not modified’ response. If so, `output_stream` will not be written to, and will be closed with a cancelled close operation. This will ensure that the existing content of the output stream (if it’s a file, for example) will not be overwritten.

Note that `last_etag` must be the ETag value returned by the server last time the file was downloaded, not the local file ETag generated by GLib.

If specified, `progress_callback` will be called zero or more times until `callback` is called, providing progress updates on the download.

#### Parameters

soup_session | a SoupSession |
uri | the URI to download. | [not nullable]
output_stream | an output stream to write the download to. | [not nullable]
last_etag | the last-known ETag of the URI, or `NULL` if unknown. | [nullable]
last_modified_date | the last-known Last-Modified date of the URI, or `NULL` if unknown. | [nullable]
io_priority | I/O priority to download and write at |
progress_callback | callback to call with progress information. | [nullable]
progress_user_data | data to pass to `progress_callback` . | [nullable][closure progress_callback]
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call once the operation is complete |
user_data | data to pass to `callback` . | [closure callback]

Since: 43

### gs_download_stream_finish ()

    gboolean
    gs_download_stream_finish (SoupSession *soup_session,
                               GAsyncResult *result,
                               gchar **new_etag_out,
                               GDateTime **new_last_modified_date_out,
                               GError **error);

Finish an asynchronous download operation started with `gs_download_stream_async()`.

#### Parameters

soup_session | a SoupSession |
result | result of the asynchronous operation |
new_etag_out | return location for the ETag of the downloaded file (which may be `NULL`), or `NULL` to ignore it. | [out callee-allocates][transfer full][optional][nullable]
new_last_modified_date_out | return location for the new Last-Modified date of the downloaded file (which may be `NULL`), or `NULL` to ignore it. | [out callee-allocates][transfer full][optional][nullable]
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 43

### gs_download_file_async ()

    void
    gs_download_file_async (SoupSession *soup_session,
                            const gchar *uri,
                            GFile *output_file,
                            int io_priority,
                            GsDownloadProgressCallback progress_callback,
                            gpointer progress_user_data,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Download `uri` and write it to `output_file` asynchronously, overwriting the existing content of `output_file` .

The ETag and modification time of `output_file` will be queried and, if known, used to skip the download if `output_file` is already up to date.

If specified, `progress_callback` will be called zero or more times until `callback` is called, providing progress updates on the download.

#### Parameters

soup_session | a SoupSession |
uri | the URI to download. | [not nullable]
output_file | an output file to write the download to. | [not nullable]
io_priority | I/O priority to download and write at |
progress_callback | callback to call with progress information. | [nullable]
progress_user_data | data to pass to `progress_callback` . | [nullable][closure progress_callback]
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call once the operation is complete |
user_data | data to pass to `callback` . | [closure callback]

Since: 42

### gs_download_file_finish ()

    gboolean
    gs_download_file_finish (SoupSession *soup_session,
                             GAsyncResult *result,
                             GError **error);

Finish an asynchronous download operation started with `gs_download_file_async()`.

#### Parameters

soup_session | a SoupSession |
result | result of the asynchronous operation |
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 42

## Types and Values

### enum GsDownloadError

#### Members

GS_DOWNLOAD_ERROR_NOT_MODIFIED |  |

### GS_DOWNLOAD_ERROR

    #define GS_DOWNLOAD_ERROR gs_download_error_quark ()