GDataPicasaWebService

GDataPicasaWebService — GData PicasaWeb service object

Stability Level

Stable, unless otherwise indicated

Object Hierarchy

    GObject
    ╰── GDataService
        ╰── GDataPicasaWebService

Includes

#include <gdata/services/picasaweb/gdata-picasaweb-service.h>

Description

GDataPicasaWebService is a subclass of GDataService for communicating with the GData API of Google PicasaWeb. It supports querying for files and albums, and uploading files.

For more details of PicasaWeb's GData API, see the online documentation.

Example 38. Authenticating and Creating a New Album

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
GDataClientLoginAuthorizer *authorizer;
GDataPicasaWebService *service;
GDataPicasaWebAlbum *album, *inserted_album;

/* Create a service object and authorize against the PicasaWeb service */
authorizer = gdata_client_login_authorizer_new ("companyName-applicationName-versionID", GDATA_TYPE_PICASAWEB_SERVICE);
gdata_client_login_authorizer_authenticate (authorizer, username, password, NULL, NULL);
service = gdata_picasaweb_service_new (GDATA_AUTHORIZER (authorizer));

/* Create a GDataPicasaWebAlbum entry for the new album, setting some information about it */
album = gdata_picasaweb_album_new (NULL);
gdata_entry_set_title (GDATA_ENTRY (album), "Photos from the Rhine");
gdata_entry_set_summary (GDATA_ENTRY (album), "An album of our adventures on the great river.");
gdata_picasaweb_album_set_location (album, "The Rhine, Germany");

/* Insert the new album on the server. Note that this is a blocking operation. */
inserted_album = gdata_picasaweb_service_insert_album (service, album, NULL, NULL);

g_object_unref (album);
g_object_unref (inserted_album);
g_object_unref (service);
g_object_unref (authorizer);


Example 39. Uploading a Photo or Video

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
GDataPicasaWebFile *file_entry, *uploaded_file_entry;
GDataUploadStream *upload_stream;
GFile *file_data;
GFileInfo *file_info;
GFileInputStream *file_stream;

/* Specify the GFile image on disk to upload */
file_data = g_file_new_for_path (path);

/* Get the file information for the file being uploaded. If another data source was being used for the upload, it would have to
 * provide an appropriate slug and content type. Note that this is a blocking operation. */
file_info = g_file_query_info (file_data, G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "," G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
                               G_FILE_QUERY_INFO_NONE, NULL, NULL);

/* Create a GDataPicasaWebFile entry for the image, setting a title and caption/summary */
file_entry = gdata_picasaweb_file_new (NULL);
gdata_entry_set_title (GDATA_ENTRY (file_entry), "Black Cat");
gdata_entry_set_summary (GDATA_ENTRY (file_entry), "Photo of the world's most beautiful cat.");

/* Create an upload stream for the file. This is non-blocking. */
upload_stream = gdata_picasaweb_service_upload_file (service, album, file_entry, g_file_info_get_display_name (file_info),
                                                     g_file_info_get_content_type (file_info), NULL, NULL);
g_object_unref (file_info);
g_object_unref (file_entry);

/* Prepare a file stream for the file to be uploaded. This is a blocking operation. */
file_stream = g_file_read (file_data, NULL, NULL);
g_object_unref (file_data);

/* Upload the file to the server. Note that this is a blocking operation. */
g_output_stream_splice (G_OUTPUT_STREAM (upload_stream), G_INPUT_STREAM (file_stream),
                        G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET, NULL, NULL);

/* Parse the resulting updated entry. This is a non-blocking operation. */
uploaded_file_entry = gdata_picasaweb_service_finish_file_upload (service, upload_stream, NULL);
g_object_unref (file_stream);
g_object_unref (upload_stream);

/* ... */

g_object_unref (uploaded_file_entry);


Functions

gdata_picasaweb_service_new ()

GDataPicasaWebService *
gdata_picasaweb_service_new (GDataAuthorizer *authorizer);

Creates a new GDataPicasaWebService using the given GDataAuthorizer. If authorizer is NULL, all requests are made as an unauthenticated user.

Parameters

authorizer

a GDataAuthorizer to authorize the service's requests, or NULL.

[allow-none]

Returns

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

Since: 0.9.0


gdata_picasaweb_service_get_primary_authorization_domain ()

GDataAuthorizationDomain *
gdata_picasaweb_service_get_primary_authorization_domain
                               (void);

The primary GDataAuthorizationDomain for interacting with PicasaWeb. This will not normally need to be used, as it's used internally by the GDataPicasaWebService methods. However, if using the plain GDataService methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests.

The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.

Returns

the service's authorization domain.

[transfer none]

Since: 0.9.0


gdata_picasaweb_service_get_user ()

GDataPicasaWebUser *
gdata_picasaweb_service_get_user (GDataPicasaWebService *self,
                                  const gchar *username,
                                  GCancellable *cancellable,
                                  GError **error);

Queries the service to return the user specified by username .

Parameters

self

a GDataPicasaWebService

 

username

the username of the user whose information you wish to retrieve, or NULL for the currently authenticated user.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

a GError, or NULL

 

Returns

a GDataPicasaWebUser; unref with g_object_unref().

[transfer full]

Since: 0.6.0


gdata_picasaweb_service_get_user_async ()

void
gdata_picasaweb_service_get_user_async
                               (GDataPicasaWebService *self,
                                const gchar *username,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Queries the service to return the user specified by username .

For more details, see gdata_picasaweb_service_get_user() which is the synchronous version of this method.

When the operation is finished, callback will be called. You can then call gdata_picasaweb_service_get_user_finish() to get the results of the operation.

Parameters

self

a GDataPicasaWebService

 

username

the username of the user whose information you wish to retrieve, or NULL for the currently authenticated user.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when the query is finished

 

user_data

data to pass to the callback function.

[closure]

Since: 0.9.1


gdata_picasaweb_service_get_user_finish ()

GDataPicasaWebUser *
gdata_picasaweb_service_get_user_finish
                               (GDataPicasaWebService *self,
                                GAsyncResult *result,
                                GError **error);

Finishes an asynchronous user retrieval operation started with gdata_picasaweb_service_get_user_async().

Parameters

self

a GDataPicasaWebService

 

result

a GAsyncResult

 

error

a GError, or NULL

 

Returns

a GDataPicasaWebUser; unref with g_object_unref().

[transfer full]

Since: 0.9.1


gdata_picasaweb_service_query_all_albums ()

GDataFeed *
gdata_picasaweb_service_query_all_albums
                               (GDataPicasaWebService *self,
                                GDataQuery *query,
                                const gchar *username,
                                GCancellable *cancellable,
                                GDataQueryProgressCallback progress_callback,
                                gpointer progress_user_data,
                                GError **error);

Queries the service to return a list of all albums belonging to the specified username which match the given query . If a user is authenticated with the service, username can be set as NULL to return a list of albums belonging to the currently-authenticated user.

Note that the “q” query parameter cannot be set on query for album queries.

For more details, see gdata_service_query().

Parameters

self

a GDataPicasaWebService

 

query

a GDataQuery with the query parameters, or NULL.

[allow-none]

username

the username of the user whose albums you wish to retrieve, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

progress_callback

a GDataQueryProgressCallback to call when an entry is loaded, or NULL.

[allow-none][scope call][closure progress_user_data]

progress_user_data

data to pass to the progress_callback function.

[closure]

error

a GError, or NULL

 

Returns

a GDataFeed of query results; unref with g_object_unref().

[transfer full]

Since: 0.4.0


gdata_picasaweb_service_query_all_albums_async ()

void
gdata_picasaweb_service_query_all_albums_async
                               (GDataPicasaWebService *self,
                                GDataQuery *query,
                                const gchar *username,
                                GCancellable *cancellable,
                                GDataQueryProgressCallback progress_callback,
                                gpointer progress_user_data,
                                GDestroyNotify destroy_progress_user_data,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Queries the service to return a list of all albums belonging to the specified username which match the given query . self , query and username are all reffed/copied when this function is called, so can safely be unreffed/freed after this function returns.

For more details, see gdata_picasaweb_service_query_all_albums(), which is the synchronous version of this function, and gdata_service_query_async(), which is the base asynchronous query function.

Parameters

self

a GDataPicasaWebService

 

query

a GDataQuery with the query parameters, or NULL.

[allow-none]

username

the username of the user whose albums you wish to retrieve, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

progress_callback

a GDataQueryProgressCallback to call when an entry is loaded, or NULL.

[allow-none][closure progress_user_data]

progress_user_data

data to pass to the progress_callback function.

[closure]

destroy_progress_user_data

the function to call when progress_callback will not be called any more, or NULL. This function will be called with progress_user_data as a parameter and can be used to free any memory allocated for it.

[allow-none]

callback

a GAsyncReadyCallback to call when authentication is finished

 

user_data

data to pass to the callback function.

[closure]

Since: 0.9.1


gdata_picasaweb_service_query_files ()

GDataFeed *
gdata_picasaweb_service_query_files (GDataPicasaWebService *self,
                                     GDataPicasaWebAlbum *album,
                                     GDataQuery *query,
                                     GCancellable *cancellable,
                                     GDataQueryProgressCallback progress_callback,
                                     gpointer progress_user_data,
                                     GError **error);

Queries the specified album for a list of the files which match the given query . If album is NULL and a user is authenticated with the service, the user's default album will be queried.

For more details, see gdata_service_query().

Parameters

self

a GDataPicasaWebService

 

album

a GDataPicasaWebAlbum from which to retrieve the files, or NULL.

[allow-none]

query

a GDataQuery with the query parameters, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

progress_callback

a GDataQueryProgressCallback to call when an entry is loaded, or NULL.

[allow-none][scope call][closure progress_user_data]

progress_user_data

data to pass to the progress_callback function.

[closure]

error

a GError, or NULL

 

Returns

a GDataFeed of query results; unref with g_object_unref().

[transfer full]

Since: 0.4.0


gdata_picasaweb_service_query_files_async ()

void
gdata_picasaweb_service_query_files_async
                               (GDataPicasaWebService *self,
                                GDataPicasaWebAlbum *album,
                                GDataQuery *query,
                                GCancellable *cancellable,
                                GDataQueryProgressCallback progress_callback,
                                gpointer progress_user_data,
                                GDestroyNotify destroy_progress_user_data,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Queries the specified album for a list of the files which match the given query . If album is NULL and a user is authenticated with the service, the user's default album will be queried. self , album and query are all reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see gdata_picasaweb_service_query_files(), which is the synchronous version of this function, and gdata_service_query_async(), which is the base asynchronous query function.

Parameters

self

a GDataPicasaWebService

 

album

a GDataPicasaWebAlbum from which to retrieve the files, or NULL.

[allow-none]

query

a GDataQuery with the query parameters, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL.

[allow-none]

progress_callback

a GDataQueryProgressCallback to call when an entry is loaded, or NULL.

[allow-none][closure progress_user_data]

progress_user_data

data to pass to the progress_callback function.

[closure]

destroy_progress_user_data

the function to call when progress_callback will not be called any more, or NULL. This function will be called with progress_user_data as a parameter and can be used to free any memory allocated for it.

[allow-none]

callback

a GAsyncReadyCallback to call when the query is finished

 

user_data

data to pass to the callback function.

[closure]

Since: 0.9.1


gdata_picasaweb_service_upload_file ()

GDataUploadStream *
gdata_picasaweb_service_upload_file (GDataPicasaWebService *self,
                                     GDataPicasaWebAlbum *album,
                                     GDataPicasaWebFile *file_entry,
                                     const gchar *slug,
                                     const gchar *content_type,
                                     GCancellable *cancellable,
                                     GError **error);

Uploads a file (photo or video) to the given PicasaWeb album , using the metadata from file and the file data written to the resulting GDataUploadStream. If album is NULL, the file will be uploaded to the currently-authenticated user's "Drop Box" album. A user must be authenticated to use this function.

If file has already been inserted, a GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED error will be returned.

If no user is authenticated with the service, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED will be returned. It is recommended to retry the upload after refreshing the authorization tokens held by the associated GDataAuthorizer using gdata_authorizer_refresh_authorization().

The stream returned by this function should be written to using the standard GOutputStream methods, asychronously or synchronously. Once the stream is closed (using g_output_stream_close()), gdata_picasaweb_service_finish_file_upload() should be called on it to parse and return the updated GDataPicasaWebFile for the uploaded file. This must be done, as file_entry isn't updated in-place.

In order to cancel the upload, a GCancellable passed in to cancellable must be cancelled using g_cancellable_cancel(). Cancelling the individual GOutputStream operations on the GDataUploadStream will not cancel the entire upload; merely the write or close operation in question. See the “cancellable” for more details.

Any upload errors will be thrown by the stream methods, and may come from the GDataServiceError domain.

Parameters

self

a GDataPicasaWebService

 

album

a GDataPicasaWebAlbum into which to insert the file, or NULL.

[allow-none]

file_entry

a GDataPicasaWebFile to insert

 

slug

the filename to give to the uploaded file

 

content_type

the content type of the uploaded data

 

cancellable

a GCancellable for the entire upload stream, or NULL.

[allow-none]

error

a GError, or NULL

 

Returns

a GDataUploadStream to write the file data to, or NULL; unref with g_object_unref().

[transfer full]

Since: 0.8.0


gdata_picasaweb_service_finish_file_upload ()

GDataPicasaWebFile *
gdata_picasaweb_service_finish_file_upload
                               (GDataPicasaWebService *self,
                                GDataUploadStream *upload_stream,
                                GError **error);

Finish off a file upload operation started by gdata_picasaweb_service_upload_file(), parsing the result and returning the new GDataPicasaWebFile.

If an error occurred during the upload operation, it will have been returned during the operation (e.g. by g_output_stream_splice() or one of the other stream methods). In such a case, NULL will be returned but error will remain unset. error is only set in the case that the server indicates that the operation was successful, but an error is encountered in parsing the result sent by the server.

Parameters

self

a GDataPicasaWebService

 

upload_stream

the GDataUploadStream from the operation

 

error

a GError, or NULL

 

Returns

the new GDataPicasaWebFile, or NULL; unref with g_object_unref().

[transfer full]

Since: 0.8.0


gdata_picasaweb_service_insert_album ()

GDataPicasaWebAlbum *
gdata_picasaweb_service_insert_album (GDataPicasaWebService *self,
                                      GDataPicasaWebAlbum *album,
                                      GCancellable *cancellable,
                                      GError **error);

Inserts a new album described by album . A user must be authenticated to use this function.

Parameters

self

a GDataPicasaWebService

 

album

a GDataPicasaWebAlbum to create on the server

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

a GError, or NULL

 

Returns

the inserted GDataPicasaWebAlbum; unref with g_object_unref().

[transfer full]

Since: 0.6.0


gdata_picasaweb_service_insert_album_async ()

void
gdata_picasaweb_service_insert_album_async
                               (GDataPicasaWebService *self,
                                GDataPicasaWebAlbum *album,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Inserts a new album described by album . The user must be authenticated to use this function. self and album are both reffed when this function is called, so can safely be unreffed after this function returns.

callback should call gdata_service_insert_entry_finish() to obtain a GDataPicasaWebAlbum representing the inserted album and to check for possible errors.

For more details, see gdata_picasaweb_service_insert_album(), which is the synchronous version of this function, and gdata_service_insert_entry_async(), which is the base asynchronous insertion function.

Parameters

self

a GDataPicasaWebService

 

album

a GDataPicasaWebAlbum to create on the server

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when insertion is finished

 

user_data

data to pass to the callback function.

[closure]

Since: 0.8.0

Types and Values

GDataPicasaWebService

typedef struct _GDataPicasaWebService GDataPicasaWebService;

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

Since: 0.4.0


GDataPicasaWebServiceClass

typedef struct {
} GDataPicasaWebServiceClass;

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

Since: 0.4.0