GData Reference Manual: GDataDownloadStream

## GDataDownloadStream GDataDownloadStream — GData download stream object |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GInputStream * | gdata_download_stream_new ()
GDataService * | gdata_download_stream_get_service ()
GDataAuthorizationDomain * | gdata_download_stream_get_authorization_domain ()
GCancellable * | gdata_download_stream_get_cancellable ()
const gchar * | gdata_download_stream_get_download_uri ()
const gchar * | gdata_download_stream_get_content_type ()
gssize | gdata_download_stream_get_content_length ()

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

## Types and Values

| GDataDownloadStream
| GDataDownloadStreamClass

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

self | a GDataDownloadStream |

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

self | a GDataDownloadStream |

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

self | a GDataDownloadStream |

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

self | a GDataDownloadStream |

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

self | a GDataDownloadStream |

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

self | a GDataDownloadStream |

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

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