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);
    GDataPicasaWebFile * gdata_picasaweb_service_upload_file
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataPicasaWebFile *file_entry,
                                                             GFile *file_data,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_picasaweb_service_upload_file_async
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataPicasaWebFile *file_entry,
                                                             GFile *file_data,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataPicasaWebFile * gdata_picasaweb_service_upload_file_finish
                                                            (GDataPicasaWebService *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GDataPicasaWebAlbum * gdata_picasaweb_service_insert_album
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GCancellable *cancellable,
                                                             GError **error);

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

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

`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_upload_file ()

    GDataPicasaWebFile * gdata_picasaweb_service_upload_file
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataPicasaWebFile *file_entry,
                                                             GFile *file_data,
                                                             GCancellable *cancellable,
                                                             GError **error);

Uploads a file (photo or video) to the given PicasaWeb `album`, using the `actual_file` from disk and the metadata from `file`. 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.

If there is a problem reading `file_data`, an error from `g_output_stream_splice()` or `g_file_query_info()` will be returned. Other errors from GDataServiceError can be returned for other exceptional conditions, as determined by the server.

`self` : | a GDataPicasaWebService
`album` : | a GDataPicasaWebAlbum into which to insert the file, or `NULL`. [allow-none]
`file_entry` : | a GDataPicasaWebFile to insert
`file_data` : | the actual file to upload
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | the inserted GDataPicasaWebFile with updated properties from `file_entry`; unref with `g_object_unref()`. [transfer full]

Since 0.4.0

### gdata_picasaweb_service_upload_file_async ()

    void                gdata_picasaweb_service_upload_file_async
                                                            (GDataPicasaWebService *self,
                                                             GDataPicasaWebAlbum *album,
                                                             GDataPicasaWebFile *file_entry,
                                                             GFile *file_data,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Uploads a file (photo or video) to the given PicasaWeb `album` asynchronously, using the `actual_file` from disk and the metadata from `file`. 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.

`callback` should call `gdata_picasaweb_service_upload_file_finish()` to obtain a GDataPicasaWebFile representing the uploaded file and check for possible errors.

`self` : | a GDataPicasaWebService
`album` : | a GDataPicasaWebAlbum into which to insert the file, or `NULL`. [allow-none]
`file_entry` : | a GDataPicasaWebFile to insert
`file_data` : | the actual file to upload
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when authentication is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.6.0

### gdata_picasaweb_service_upload_file_finish ()

    GDataPicasaWebFile * gdata_picasaweb_service_upload_file_finish
                                                            (GDataPicasaWebService *self,
                                                             GAsyncResult *result,
                                                             GError **error);

This should be called to obtain the result of a call to `gdata_picasaweb_service_upload_file_async()` and to check for errors.

If there is a problem reading the subect file's data, an error from `g_output_stream_splice()` or `g_file_query_info()` will be returned. Other errors from GDataServiceError can be returned for other exceptional conditions, as determined by the server.

If the file to upload has already been inserted, a `GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED` error will be set. If no user is authenticated with the service when trying to upload it, `GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED` will be set.

`self` : | a GDataPicasaWebService
`result` : | a GSimpleAsyncResult
`error` : | a GError, or `NULL`
Returns : | the inserted GDataPicasaWebFile; unref with `g_object_unref()`. [transfer full]

Since 0.6.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