GDataUploadStream

GDataUploadStream — GData upload stream object

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

                    GDataUploadStream;
                    GDataUploadStreamClass;
GOutputStream *     gdata_upload_stream_new             (GDataService *service,
                                                         const gchar *method,
                                                         const gchar *upload_uri,
                                                         GDataEntry *entry,
                                                         const gchar *slug,
                                                         const gchar *content_type);
const gchar *       gdata_upload_stream_get_response    (GDataUploadStream *self,
                                                         gssize *length);
GDataService *      gdata_upload_stream_get_service     (GDataUploadStream *self);
const gchar *       gdata_upload_stream_get_upload_uri  (GDataUploadStream *self);
GDataEntry *        gdata_upload_stream_get_entry       (GDataUploadStream *self);
const gchar *       gdata_upload_stream_get_slug        (GDataUploadStream *self);
const gchar *       gdata_upload_stream_get_content_type
                                                        (GDataUploadStream *self);

Object Hierarchy

  GObject
   +----GOutputStream
         +----GDataUploadStream

Properties

  "content-type"             gchar*                : Read / Write / Construct Only
  "entry"                    GDataEntry*           : Read / Write / Construct Only
  "service"                  GDataService*         : Read / Write / Construct Only
  "slug"                     gchar*                : Read / Write / Construct Only
  "upload-uri"               gchar*                : Read / Write / Construct Only

Description

GDataUploadStream is a GOutputStream subclass to allow uploading of files from GData services with authentication from a GDataService.

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 the file is being uploaded.

Uploads of a file, or a file with associated metadata (a GDataEntry) may take place, 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.

Details

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


gdata_upload_stream_new ()

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

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.

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

service :

a GDataService

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

Returns :

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

Since 0.5.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. Once the stream has been closed, all network communication is guaranteed to have finished.

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 authenticate the upload, as passed to gdata_upload_stream_new().

self :

a GDataUploadStream

Returns :

the GDataService used to authenticate the upload. [transfer none]

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

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

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.

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.

self :

a GDataUploadStream

Returns :

the content type of the file being uploaded

Since 0.5.0

Property Details

The "content-type" property

  "content-type"             gchar*                : Read / Write / Construct Only

The content type of the file being uploaded.

Default value: NULL

Since 0.5.0


The "entry" property

  "entry"                    GDataEntry*           : Read / Write / Construct Only

The entry used for metadata to upload.

Since 0.5.0


The "service" property

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

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

Since 0.5.0


The "slug" property

  "slug"                     gchar*                : Read / Write / Construct Only

The slug of the file being uploaded.

Default value: NULL

Since 0.5.0


The "upload-uri" property

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

The URI of the file to upload.

Default value: NULL

Since 0.5.0