manpagez: man pages & more
html files: gdata
Home | html | info | man

GDataDownloadStream

GDataDownloadStream — GData download stream object

Stability Level

Stable, unless otherwise indicated

Properties

GDataAuthorizationDomain * authorization-domain Read / Write / Construct Only
GCancellable * cancellable Read / Write / Construct Only
glong content-length Read
gchar * content-type Read
gchar * download-uri Read / Write / Construct Only
GDataService * service Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GInputStream
        ╰── GDataDownloadStream

Implemented Interfaces

GDataDownloadStream implements GSeekable.

Includes

#include <gdata/gdata-download-stream.h>

Description

GDataDownloadStream is a GInputStream subclass to allow downloading of files from GData services with authorization from a GDataService under the given GDataAuthorizationDomain. If authorization is not required to perform the download, a GDataAuthorizationDomain doesn't have to be specified.

Once a GDataDownloadStream is instantiated with gdata_download_stream_new(), the standard GInputStream API can be used on the stream to download the file. Network communication may not actually begin until the first call to g_input_stream_read(), so having a GDataDownloadStream around is no guarantee that the file is being downloaded.

The content type and length of the file being downloaded are made available through “content-type” and “content-length” as soon as the appropriate data is received from the server. Connect to the “notify” content-type and content-length details to be notified as soon as the data is available.

The entire download operation can be cancelled using the GCancellable instance provided to gdata_download_stream_new(), or returned by gdata_download_stream_get_cancellable(). Cancelling this at any time will cause all future GInputStream method calls to return G_IO_ERROR_CANCELLED. If any GInputStream methods are in the process of being called, they will be cancelled and return G_IO_ERROR_CANCELLED as soon as possible.

Note that cancelling an individual method call (such as a call to g_input_stream_read()) using the GCancellable parameter of the method will not cancel the download as a whole — just that particular method call. In the case of g_input_stream_read(), this will cause it to successfully return any data that it has in memory at the moment (up to the requested number of bytes), or return a G_IO_ERROR_CANCELLED if it was blocking on receiving data from the network. This is also the behaviour of g_input_stream_read() when the download operation as a whole is cancelled.

In the case of g_input_stream_close(), the call will return immediately if network activity hasn't yet started. If it has, the network activity will be cancelled, regardless of whether the call to g_input_stream_close() is cancelled. Cancelling a pending call to g_input_stream_close() (either using the method's GCancellable, or by cancelling the download stream as a whole) will cause it to stop waiting for the network activity to finish, and return G_IO_ERROR_CANCELLED immediately. Network activity will continue to be shut down in the background.

If the server returns an error message (for example, if the user is not correctly authenticated/authorized or doesn't have suitable permissions to download from the given URI), it will be returned as a GDataServiceError by the first call to g_input_stream_read().

Example 2. Downloading to a File

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
GDataService *service;
GDataAuthorizationDomain *domain;
GCancellable *cancellable;
GInputStream *download_stream;
GOutputStream *output_stream;

/* Create the download stream */
service = create_my_service ();
domain = get_my_authorization_domain_from_service (service);
cancellable = g_cancellable_new (); /* cancel this to cancel the entire download operation */
download_stream = gdata_download_stream_new (service, domain, download_uri, cancellable);
output_stream = create_file_and_return_output_stream ();

/* Perform the download asynchronously */
g_output_stream_splice_async (output_stream, download_stream, G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET,
                              G_PRIORITY_DEFAULT, NULL, (GAsyncReadyCallback) download_splice_cb, NULL);

g_object_unref (output_stream);
g_object_unref (download_stream);
g_object_unref (cancellable);
g_object_unref (domain);
g_object_unref (service);

static void
download_splice_cb (GOutputStream *output_stream, GAsyncResult *result, gpointer user_data)
{
    GError *error = NULL;

    g_output_stream_splice_finish (output_stream, result, &error);

    if (error != NULL && g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED) == FALSE)) {
        /* Error downloading the file; potentially an I/O error (GIOError), or an error response from the server
         * (GDataServiceError). You might want to delete the newly created file because of the error. */
        g_error ("Error downloading file: %s", error->message);
        g_error_free (error);
    }
}

Functions

gdata_download_stream_new ()

GInputStream *
gdata_download_stream_new (GDataService *service,
                           GDataAuthorizationDomain *domain,
                           const gchar *download_uri,
                           GCancellable *cancellable);

Creates a new GDataDownloadStream, allowing a file to be downloaded from a GData service using standard GInputStream API.

As well as the standard GIO errors, calls to the GInputStream API on a GDataDownloadStream can also return any relevant specific error from GDataServiceError, or GDATA_SERVICE_ERROR_PROTOCOL_ERROR in the general case.

If a GCancellable is provided in cancellable , the download operation may be cancelled at any time from another thread using g_cancellable_cancel(). In this case, any ongoing network activity will be stopped, and any pending or future calls to GInputStream API on the GDataDownloadStream will return G_IO_ERROR_CANCELLED. Note that the GCancellable objects which can be passed to individual GInputStream operations will not cancel the download operation proper if cancelled — they will merely cancel that API call. The only way to cancel the download operation completely is using this cancellable .

Parameters

service

a GDataService

 

domain

the GDataAuthorizationDomain to authorize the download, or NULL.

[allow-none]

download_uri

the URI to download; this must be HTTPS

 

cancellable

a GCancellable for the entire download stream, or NULL.

[allow-none]

Returns

a new GInputStream, or NULL; unref with g_object_unref()

Since: 0.9.0


gdata_download_stream_get_service ()

GDataService *
gdata_download_stream_get_service (GDataDownloadStream *self);

Gets the service used to authorize the download, as passed to gdata_download_stream_new().

Parameters

Returns

the GDataService used to authorize the download.

[transfer none]

Since: 0.5.0


gdata_download_stream_get_authorization_domain ()

GDataAuthorizationDomain *
gdata_download_stream_get_authorization_domain
                               (GDataDownloadStream *self);

Gets the authorization domain used to authorize the download, as passed to gdata_download_stream_new(). It may be NULL if authorization is not needed for the download.

Parameters

Returns

the GDataAuthorizationDomain used to authorize the download, or NULL.

[transfer none][allow-none]

Since: 0.9.0


gdata_download_stream_get_cancellable ()

GCancellable *
gdata_download_stream_get_cancellable (GDataDownloadStream *self);

Gets the GCancellable for the entire download operation, “cancellable”.

Parameters

Returns

the GCancellable for the entire download operation.

[transfer none]

Since: 0.8.0


gdata_download_stream_get_download_uri ()

const gchar *
gdata_download_stream_get_download_uri
                               (GDataDownloadStream *self);

Gets the URI of the file being downloaded, as passed to gdata_download_stream_new().

Parameters

Returns

the URI of the file being downloaded

Since: 0.5.0


gdata_download_stream_get_content_type ()

const gchar *
gdata_download_stream_get_content_type
                               (GDataDownloadStream *self);

Gets the content type of the file being downloaded. If the Content-Type header has not yet been received, NULL will be returned.

Parameters

Returns

the content type of the file being downloaded, or NULL

Since: 0.5.0


gdata_download_stream_get_content_length ()

gssize
gdata_download_stream_get_content_length
                               (GDataDownloadStream *self);

Gets the length (in bytes) of the file being downloaded. If the Content-Length header has not yet been received from the server, -1 will be returned.

Parameters

Returns

the content length of the file being downloaded, or -1

Since: 0.5.0

Types and Values

GDataDownloadStream

typedef struct _GDataDownloadStream GDataDownloadStream;

All the fields in the GDataDownloadStream structure are private and should never be accessed directly.

Since: 0.5.0


GDataDownloadStreamClass

typedef struct {
} GDataDownloadStreamClass;

All the fields in the GDataDownloadStreamClass structure are private and should never be accessed directly.

Since: 0.5.0

Property Details

The “authorization-domain” property

  “authorization-domain”     GDataAuthorizationDomain *

The authorization domain for the download, against which the “authorizer” for the “service” should be authorized. This may be NULL if authorization is not needed for the download.

Flags: Read / Write / Construct Only

Since: 0.9.0


The “cancellable” property

  “cancellable”              GCancellable *

An optional cancellable used to cancel the entire download operation. If a GCancellable instance isn't provided for this property at construction time (i.e. to gdata_download_stream_new()), one will be created internally and can be retrieved using gdata_download_stream_get_cancellable() and used to cancel the download operation with g_cancellable_cancel() just as if it was passed to gdata_download_stream_new().

If the download operation is cancelled using this GCancellable, any ongoing network activity will be stopped, and any pending or future calls to GInputStream API on the GDataDownloadStream will return G_IO_ERROR_CANCELLED. Note that the GCancellable objects which can be passed to individual GInputStream operations will not cancel the download operation proper if cancelled — they will merely cancel that API call. The only way to cancel the download operation completely is using “cancellable”.

Flags: Read / Write / Construct Only

Since: 0.8.0


The “content-length” property

  “content-length”           glong

The length (in bytes) of the file being downloaded. This will initially be -1, and will be populated as soon as the appropriate header is received from the server. Its value will never change after this.

Note that change notifications for this property (“notify” emissions) may be emitted in threads other than the one which created the GDataDownloadStream. It is the client's responsibility to ensure that any notification signal handlers are either multi-thread safe or marshal the notification to the thread which owns the GDataDownloadStream as appropriate.

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.5.0


The “content-type” property

  “content-type”             gchar *

The content type of the file being downloaded. This will initially be NULL, and will be populated as soon as the appropriate header is received from the server. Its value will never change after this.

Note that change notifications for this property (“notify” emissions) may be emitted in threads other than the one which created the GDataDownloadStream. It is the client's responsibility to ensure that any notification signal handlers are either multi-thread safe or marshal the notification to the thread which owns the GDataDownloadStream as appropriate.

Flags: Read

Default value: NULL

Since: 0.5.0


The “download-uri” property

  “download-uri”             gchar *

The URI of the file to download. This must be HTTPS.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.5.0


The “service” property

  “service”                  GDataService *

The service which is used to authorize the download, and to which the download relates.

Flags: Read / Write / Construct Only

Since: 0.5.0

© manpagez.com 2000-2022
Individual documents may contain additional copyright information.