GDataUploadStream: GData Reference Manual

## GDataUploadStream GDataUploadStream — GData upload stream object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GOutputStream * | gdata_upload_stream_new ()
GOutputStream * | gdata_upload_stream_new_resumable ()
const gchar * | gdata_upload_stream_get_response ()
GDataService * | gdata_upload_stream_get_service ()
GDataAuthorizationDomain * | gdata_upload_stream_get_authorization_domain ()
GCancellable * | gdata_upload_stream_get_cancellable ()
const gchar * | gdata_upload_stream_get_method ()
const gchar * | gdata_upload_stream_get_upload_uri ()
GDataEntry * | gdata_upload_stream_get_entry ()
const gchar * | gdata_upload_stream_get_slug ()
const gchar * | gdata_upload_stream_get_content_type ()
goffset | gdata_upload_stream_get_content_length ()

## Properties

GDataAuthorizationDomain * | authorization-domain | Read / Write / Construct Only
GCancellable * | cancellable | Read / Write / Construct Only
gint64 | content-length | Read / Write / Construct Only
gchar * | content-type | Read / Write / Construct Only
GDataEntry * | entry | Read / Write / Construct Only
gchar * | method | Read / Write / Construct Only
GDataService * | service | Read / Write / Construct Only
gchar * | slug | Read / Write / Construct Only
gchar * | upload-uri | Read / Write / Construct Only

## Types and Values

#define | GDATA_LINK_RESUMABLE_CREATE_MEDIA
#define | GDATA_LINK_RESUMABLE_EDIT_MEDIA
| GDataUploadStream
| GDataUploadStreamClass

## Object Hierarchy

        GObject
        ╰── GOutputStream
            ╰── GDataUploadStream

## Includes

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

## Description

GDataUploadStream is a GOutputStream subclass to allow uploading of files from GData services with authorization from a GDataService under the given GDataAuthorizationDomain. If authorization is not required to perform the upload, a GDataAuthorizationDomain doesn't have to be specified.

Once a GDataUploadStream is instantiated with `gdata_upload_stream_new()`, the standard GOutputStream API can be used on the stream to upload the file. Network communication may not actually begin until the first call to `g_output_stream_write()`, so having a GDataUploadStream around is no guarantee that data is being uploaded.

Uploads of a file, or a file with associated metadata (a GDataEntry) should use GDataUploadStream, but if you want to simply upload a single GDataEntry, use `gdata_service_insert_entry()` instead. GDataUploadStream is for large streaming uploads.

Once an upload is complete, the server's response can be retrieved from the GDataUploadStream using `gdata_upload_stream_get_response()`. In order for network communication to be guaranteed to have stopped (and thus the response definitely available), `g_output_stream_close()` must be called on the GDataUploadStream first. Otherwise, `gdata_upload_stream_get_response()` may return saying that the operation is still in progress.

If the server returns an error instead of a success response, the error will be returned by `g_output_stream_close()` as a GDataServiceError.

The entire upload operation can be cancelled using the GCancellable instance provided to `gdata_upload_stream_new()`, or returned by `gdata_upload_stream_get_cancellable()`. Cancelling this at any time will cause all future GOutputStream method calls to return `G_IO_ERROR_CANCELLED`. If any GOutputStream 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_output_stream_write()`) using the GCancellable parameter of the method will not cancel the upload as a whole — just that particular method call. In the case of `g_output_stream_write()`, this will cause it to return the number of bytes it has successfully written up to the point of cancellation (up to the requested number of bytes), or return a `G_IO_ERROR_CANCELLED` if it had not managed to write any bytes to the network by that point. This is also the behaviour of `g_output_stream_write()` when the upload operation as a whole is cancelled.

In the case of `g_output_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_output_stream_close()` is cancelled. Cancelling a pending call to `g_output_stream_close()` (either using the method's GCancellable, or by cancelling the upload 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.

Any outstanding data is guaranteed to be written to the network successfully even if a call to `g_output_stream_close()` is cancelled. However, if the upload stream as a whole is cancelled using “cancellable”, no more data will be sent over the network, and the network connection will be closed immediately. i.e. GDataUploadStream will do its best to instruct the server to cancel the upload and any associated server-side changes of state.

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

Example 3. Uploading from 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
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    GDataService *service;
    GDataAuthorizationDomain *domain;
    GCancellable *cancellable;
    GInputStream *input_stream;
    GOutputStream *upload_stream;
    GFile *file;
    GFileInfo *file_info;
    GError *error = NULL;

    /* Get the file to upload */
    file = get_file_to_upload ();
    file_info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "," G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
                                   G_FILE_ATTRIBUTE_STANDARD_SIZE,
                                   G_FILE_QUERY_INFO_NONE, NULL, &error);

    if (file_info == NULL) {
        g_error ("Error getting file info: %s", error->message);
        g_error_free (error);
        g_object_unref (file);
        return;
    }

    input_stream = g_file_read (file, NULL, &error);
    g_object_unref (file);

    if (input_stream == NULL) {
        g_error ("Error getting file input stream: %s", error->message);
        g_error_free (error);
        g_object_unref (file_info);
        return;
    }

    /* Create the upload stream */
    service = create_my_service ();
    domain = get_my_authorization_domain_from_service (service);
    cancellable = g_cancellable_new (); /* cancel this to cancel the entire upload operation */
    upload_stream = gdata_upload_stream_new_resumable (service, domain, SOUP_METHOD_POST, upload_uri, NULL,
                                                       g_file_info_get_display_name (file_info), g_file_info_get_content_type (file_info),
                                                       g_file_info_get_size (file_info), cancellable);
    g_object_unref (file_info);

    /* Perform the upload asynchronously */
    g_output_stream_splice_async (upload_stream, input_stream, G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET,
                                  G_PRIORITY_DEFAULT, NULL, (GAsyncReadyCallback) upload_splice_cb, NULL);

    g_object_unref (upload_stream);
    g_object_unref (input_stream);
    g_object_unref (cancellable);
    g_object_unref (domain);
    g_object_unref (service);

    static void
    upload_splice_cb (GOutputStream *upload_stream, GAsyncResult *result, gpointer user_data)
    {
        gssize length;
        GError *error = NULL;

        g_output_stream_splice_finish (upload_stream, result, &error);

        if (error != NULL && g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED) == FALSE)) {
            /* Error upload the file; potentially an I/O error (GIOError), or an error response from the server
             * (GDataServiceError). */
            g_error ("Error uploading file: %s", error->message);
            g_error_free (error);
        }

        /* If the upload was successful, carry on to parse the result. Note that this will normally be handled by methods like
         * gdata_youtube_service_finish_video_upload(), gdata_picasaweb_service_finish_file_upload() and
         * gdata_documents_service_finish_upload() */
        parse_server_result (gdata_upload_stream_get_response (GDATA_UPLOAD_STREAM (upload_stream), &length), length);
    }

## Functions

### gdata_upload_stream_new ()

    GOutputStream *
    gdata_upload_stream_new (GDataService *service,
                             GDataAuthorizationDomain *domain,
                             const gchar *method,
                             const gchar *upload_uri,
                             GDataEntry *entry,
                             const gchar *slug,
                             const gchar *content_type,
                             GCancellable *cancellable);

Creates a new GDataUploadStream, allowing a file to be uploaded from a GData service using standard GOutputStream API.

The HTTP method to use should be specified in `method` , and will typically be either `SOUP_METHOD_POST` (for insertions) or `SOUP_METHOD_PUT` (for updates), according to the server and the `upload_uri` .

If `entry` is specified, it will be attached to the upload as the entry to which the file being uploaded belongs. Otherwise, just the file written to the stream will be uploaded, and given a default entry as determined by the server.

`slug` and `content_type` must be specified before the upload begins, as they describe the file being streamed. `slug` is the filename given to the file, which will typically be stored on the server and made available when downloading the file again. `content_type` must be the correct content type for the file, and should be in the service's list of acceptable content types.

As well as the standard GIO errors, calls to the GOutputStream API on a GDataUploadStream 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 upload 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 GOutputStream API on the GDataUploadStream will return `G_IO_ERROR_CANCELLED`. Note that the GCancellable objects which can be passed to individual GOutputStream operations will not cancel the upload operation proper if cancelled — they will merely cancel that API call. The only way to cancel the upload operation completely is using this `cancellable` .

Note that network communication won't begin until the first call to `g_output_stream_write()` on the GDataUploadStream.

#### Parameters

service | a GDataService |
domain | the GDataAuthorizationDomain to authorize the upload, or `NULL`. | [allow-none]
method | the HTTP method to use |
upload_uri | the URI to upload |
entry | the entry to upload as metadata, or `NULL`. | [allow-none]
slug | the file's slug (filename) |
content_type | the content type of the file being uploaded |
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]

#### Returns

a new GOutputStream, or `NULL`; unref with `g_object_unref()`

Since: 0.9.0

### gdata_upload_stream_new_resumable ()

    GOutputStream *
    gdata_upload_stream_new_resumable (GDataService *service,
                                       GDataAuthorizationDomain *domain,
                                       const gchar *method,
                                       const gchar *upload_uri,
                                       GDataEntry *entry,
                                       const gchar *slug,
                                       const gchar *content_type,
                                       goffset content_length,
                                       GCancellable *cancellable);

Creates a new resumable GDataUploadStream, allowing a file to be uploaded from a GData service using standard GOutputStream API. The upload will use GData's resumable upload API, so should be more reliable than a normal upload (especially if the file is large). See the

GData documentation on resumable uploads for more

information.

The HTTP method to use should be specified in `method` , and will typically be either `SOUP_METHOD_POST` (for insertions) or `SOUP_METHOD_PUT` (for updates), according to the server and the `upload_uri` .

If `entry` is specified, it will be attached to the upload as the entry to which the file being uploaded belongs. Otherwise, just the file written to the stream will be uploaded, and given a default entry as determined by the server.

`slug` , `content_type` and `content_length` must be specified before the upload begins, as they describe the file being streamed. `slug` is the filename given to the file, which will typically be stored on the server and made available when downloading the file again. `content_type` must be the correct content type for the file, and should be in the service's list of acceptable content types. `content_length` must be the size of the file being uploaded (not including the XML for any associated GDataEntry) in bytes. Zero is accepted if a metadata-only upload is being performed.

As well as the standard GIO errors, calls to the GOutputStream API on a GDataUploadStream 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 upload 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 GOutputStream API on the GDataUploadStream will return `G_IO_ERROR_CANCELLED`. Note that the GCancellable objects which can be passed to individual GOutputStream operations will not cancel the upload operation proper if cancelled — they will merely cancel that API call. The only way to cancel the upload operation completely is using this `cancellable` .

Note that network communication won't begin until the first call to `g_output_stream_write()` on the GDataUploadStream.

#### Parameters

service | a GDataService |
domain | the GDataAuthorizationDomain to authorize the upload, or `NULL`. | [allow-none]
method | the HTTP method to use |
upload_uri | the URI to upload |
entry | the entry to upload as metadata, or `NULL`. | [allow-none]
slug | the file's slug (filename) |
content_type | the content type of the file being uploaded |
content_length | the size (in bytes) of the file being uploaded |
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]

#### Returns

a new GOutputStream, or `NULL`; unref with `g_object_unref()`

Since: 0.13.0

### gdata_upload_stream_get_response ()

    const gchar *
    gdata_upload_stream_get_response (GDataUploadStream *self,
                                      gssize *length);

Returns the server's response to the upload operation performed by the GDataUploadStream. If the operation is still underway, or the server's response hasn't been received yet, `NULL` is returned and `length` is set to `-1`.

If there was an error during the upload operation (but it is complete), `NULL` is returned, and `length` is set to `0`.

While it is safe to call this function from any thread at any time during the network operation, the only way to guarantee that the response has been set before calling this function is to have closed the GDataUploadStream by calling `g_output_stream_close()` on it, without cancelling the close operation. Once the stream has been closed, all network communication is guaranteed to have finished. Note that if a call to `g_output_stream_close()` is cancelled, `g_output_stream_is_closed()` will immediately start to return `TRUE`, even if the GDataUploadStream is still attempting to flush the network buffers asynchronously — consequently, `gdata_upload_stream_get_response()` may still return `NULL` and a `length` of

`-1`. The only reliable way to determine if the stream has been fully closed in this situation is to check the results

of `gdata_upload_stream_get_response()`, rather than `g_output_stream_is_closed()`.

#### Parameters

self | a GDataUploadStream |
length | return location for the length of the response, or `NULL`. | [allow-none][out caller-allocates]

#### Returns

the server's response to the upload, or `NULL`

Since: 0.5.0

### gdata_upload_stream_get_service ()

    GDataService *
    gdata_upload_stream_get_service (GDataUploadStream *self);

Gets the service used to authorize the upload, as passed to `gdata_upload_stream_new()`.

#### Parameters

self | a GDataUploadStream |

#### Returns

the GDataService used to authorize the upload.

[transfer none]

Since: 0.5.0

### gdata_upload_stream_get_authorization_domain ()

    GDataAuthorizationDomain *
    gdata_upload_stream_get_authorization_domain
                                   (GDataUploadStream *self);

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

#### Parameters

self | a GDataUploadStream |

#### Returns

the GDataAuthorizationDomain used to authorize the upload, or `NULL`.

[transfer none][allow-none]

Since: 0.9.0

### gdata_upload_stream_get_cancellable ()

    GCancellable *
    gdata_upload_stream_get_cancellable (GDataUploadStream *self);

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

#### Parameters

self | a GDataUploadStream |

#### Returns

the GCancellable for the entire upload operation.

[transfer none]

Since: 0.8.0

### gdata_upload_stream_get_method ()

    const gchar *
    gdata_upload_stream_get_method (GDataUploadStream *self);

Gets the HTTP request method being used to upload the file, as passed to `gdata_upload_stream_new()`.

#### Parameters

self | a GDataUploadStream |

#### Returns

the HTTP request method in use

Since: 0.7.0

### gdata_upload_stream_get_upload_uri ()

    const gchar *
    gdata_upload_stream_get_upload_uri (GDataUploadStream *self);

Gets the URI the file is being uploaded to, as passed to `gdata_upload_stream_new()`.

#### Parameters

self | a GDataUploadStream |

#### Returns

the URI which the file is being uploaded to

Since: 0.5.0

### gdata_upload_stream_get_entry ()

    GDataEntry *
    gdata_upload_stream_get_entry (GDataUploadStream *self);

Gets the entry being used to upload metadata, if one was passed to `gdata_upload_stream_new()`.

#### Parameters

self | a GDataUploadStream |

#### Returns

the entry used for metadata, or `NULL`.

[transfer none]

Since: 0.5.0

### gdata_upload_stream_get_slug ()

    const gchar *
    gdata_upload_stream_get_slug (GDataUploadStream *self);

Gets the slug (filename) of the file being uploaded.

#### Parameters

self | a GDataUploadStream |

#### Returns

the slug of the file being uploaded

Since: 0.5.0

### gdata_upload_stream_get_content_type ()

    const gchar *
    gdata_upload_stream_get_content_type (GDataUploadStream *self);

Gets the content type of the file being uploaded.

#### Parameters

self | a GDataUploadStream |

#### Returns

the content type of the file being uploaded

Since: 0.5.0

### gdata_upload_stream_get_content_length ()

    goffset
    gdata_upload_stream_get_content_length
                                   (GDataUploadStream *self);

Gets the size (in bytes) of the file being uploaded. This will be `-1` for a non-resumable upload, and zero or greater for a resumable upload.

#### Parameters

self | a GDataUploadStream |

#### Returns

the size of the file being uploaded

Since: 0.13.0

## Types and Values

### GDATA_LINK_RESUMABLE_CREATE_MEDIA

    #define GDATA_LINK_RESUMABLE_CREATE_MEDIA "http://schemas.google.com/g/2005#resumable-create-media"

The relation type URI of the resumable upload location for resources attached to this resource.

For more information, see the

GData resumable upload protocol specification.

Since: 0.13.0

### GDATA_LINK_RESUMABLE_EDIT_MEDIA

    #define GDATA_LINK_RESUMABLE_EDIT_MEDIA "http://schemas.google.com/g/2005#resumable-edit-media"

The relation type URI of the resumable update location for resources attached to this resource.

For more information, see the

GData resumable upload protocol specification.

Since: 0.13.0

### GDataUploadStream

    typedef struct _GDataUploadStream GDataUploadStream;

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

Since: 0.5.0

### GDataUploadStreamClass

    typedef struct {
    } GDataUploadStreamClass;

All the fields in the GDataUploadStreamClass 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 upload, against which the “authorizer” for the “service” should be authorized. This may be `NULL` if authorization is not needed for the upload.

Flags: Read / Write / Construct Only

Since: 0.9.0

### The `“cancellable”` property

      “cancellable”              GCancellable *

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

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

Flags: Read / Write / Construct Only

Since: 0.8.0

### The `“content-length”` property

      “content-length”           gint64

The content length (in bytes) of the file being uploaded (i.e. as returned by `g_file_info_get_size()`). Note that this does not include the length of the XML serialisation of “entry”, if set.

If this is `-1` the upload will be non-resumable; if it is non-negative, the upload will be resumable.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

Since: 0.13.0

### The `“content-type”` property

      “content-type”             gchar *

The content type of the file being uploaded (i.e. as returned by `g_file_info_get_content_type()`).

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.5.0

### The `“entry”` property

      “entry”                    GDataEntry *

The entry used for metadata to upload.

Flags: Read / Write / Construct Only

Since: 0.5.0

### The `“method”` property

      “method”                   gchar *

The HTTP request method to use when uploading the file.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.7.0

### The `“service”` property

      “service”                  GDataService *

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

Flags: Read / Write / Construct Only

Since: 0.5.0

### The `“slug”` property

      “slug”                     gchar *

The slug of the file being uploaded. This is usually the display name of the file (i.e. as returned by `g_file_info_get_display_name()`).

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.5.0

### The `“upload-uri”` property

      “upload-uri”               gchar *

The URI to upload the data and metadata to.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.5.0