gs-download-utils

gs-download-utils — Download and HTTP utilities

Functions

Types and Values

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 ()