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.

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.

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

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

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.

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

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

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

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

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.

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.

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.

Since: 0.13.0

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

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. This must be HTTPS.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.5.0