GDataPicasaWebService

## GDataPicasaWebService GDataPicasaWebService — GData PicasaWeb service object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataPicasaWebService;
                        GDataPicasaWebServiceClass;
    GDataPicasaWebService * gdata_picasaweb_service_new     (const gchar *client_id);
    GDataPicasaWebUser * gdata_picasaweb_service_get_user   (GDataPicasaWebService *self,
                                                             const gchar *username,
                                                             GCancellable *cancellable,
                                                             GError **error);
    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);
    void                gdata_picasaweb_service_query_all_albums_async
                                                            (GDataPicasaWebService *self,
                                                             GDataQuery *query,
                                                             const gchar *username,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_picasaweb_service_query_files (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_picasaweb_service_query_files_async
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataUploadStream * gdata_picasaweb_service_upload_file (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataPicasaWebFile *file_entry,
                                                             const gchar *slug,
                                                             const gchar *content_type,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDataPicasaWebFile * gdata_picasaweb_service_finish_file_upload
                                                            (GDataPicasaWebService *self,
                                                             GDataUploadStream *upload_stream,
                                                             GError **error);
    GDataPicasaWebAlbum * gdata_picasaweb_service_insert_album
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_picasaweb_service_insert_album_async
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GDataService
             +----GDataPicasaWebService

## 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 29. 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
    GDataPicasaWebService *service;
    GDataPicasaWebAlbum *album, *inserted_album;

    /* Create a service object and authenticate with the PicasaWeb server */
    service = gdata_picasaweb_service_new ("companyName-applicationName-versionID");
    gdata_service_authenticate (GDATA_SERVICE (service), username, password, NULL, NULL);

    /* 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);

Example 30. 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);

## Details

### 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

### gdata_picasaweb_service_new ()

    GDataPicasaWebService * gdata_picasaweb_service_new     (const gchar *client_id);

Creates a new GDataPicasaWebService. The `client_id` must be unique for your application, and as registered with Google. The recommended form is "companyName-applicationName-versionID".

`client_id` : | your application's client ID
Returns : | a new GDataPicasaWebService, or `NULL`

Since 0.4.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`.

`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`
`error` : | a GError, or `NULL`
Returns : | a GDataPicasaWebUser; unref with `g_object_unref()`. [transfer full]

Since 0.6.0

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

`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`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [scope call]
`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,
                                                             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.

`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`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`callback` : | a GAsyncReadyCallback to call when authentication is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.4.0

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

`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`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [scope call]
`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,
                                                             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.

`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`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.8.0

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

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.

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

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

`self` : | a GDataPicasaWebService
`album` : | a GDataPicasaWebAlbum to create on the server
`cancellable` : | optional GCancellable object, or `NULL`
`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.

`self` : | a GDataPicasaWebService
`album` : | a GDataPicasaWebAlbum to create on the server
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when insertion is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.8.0