GDataDownloadStream

## GDataDownloadStream GDataDownloadStream — GData download stream object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataDownloadStream;
                        GDataDownloadStreamClass;
    GInputStream *      gdata_download_stream_new           (GDataService *service,
                                                             GDataAuthorizationDomain *domain,
                                                             const gchar *download_uri,
                                                             GCancellable *cancellable);
    GDataService *      gdata_download_stream_get_service   (GDataDownloadStream *self);
    GDataAuthorizationDomain * gdata_download_stream_get_authorization_domain
                                                            (GDataDownloadStream *self);
    GCancellable *      gdata_download_stream_get_cancellable
                                                            (GDataDownloadStream *self);
    const gchar *       gdata_download_stream_get_download_uri
                                                            (GDataDownloadStream *self);
    const gchar *       gdata_download_stream_get_content_type
                                                            (GDataDownloadStream *self);
    gssize              gdata_download_stream_get_content_length
                                                            (GDataDownloadStream *self);

## Object Hierarchy

      GObject
       +----GInputStream
             +----GDataDownloadStream

## Implemented Interfaces

GDataDownloadStream implements GSeekable.

## Properties

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

## 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);
        }
    }

## Details

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

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

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

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

`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".

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

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

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

`self` : | a GDataDownloadStream
Returns : | the content length of the file being downloaded, or `-1`

Since 0.5.0

## Property Details

### The `"authorization-domain"` property

      "authorization-domain"     GDataAuthorizationDomain*  : Read / Write / Construct Only

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.

Since 0.9.0

### The `"cancellable"` property

      "cancellable"              GCancellable*         : Read / Write / Construct Only

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

Since 0.8.0

### The `"content-length"` property

      "content-length"           glong                 : Read

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.

Allowed values: >= -1

Default value: -1

Since 0.5.0

### The `"content-type"` property

      "content-type"             gchar*                : Read

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.

Default value: NULL

Since 0.5.0

### The `"download-uri"` property

      "download-uri"             gchar*                : Read / Write / Construct Only

The URI of the file to download.

Default value: NULL

Since 0.5.0

### The `"service"` property

      "service"                  GDataService*         : Read / Write / Construct Only

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

Since 0.5.0