| Top |  |
 |
 |
 |
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 |
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 |
||
domain |
the GDataAuthorizationDomain to authorize the download, or |
[allow-none] |
download_uri |
the URI to download; this must be HTTPS |
|
cancellable |
a GCancellable for the entire download stream, or |
[allow-none] |
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().
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.
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”.
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().
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.
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.
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. This must be HTTPS.
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