GDataBatchOperation

GDataBatchOperation — GData batch operation object

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <gdata/gdata-batch-operation.h>

                    GDataBatchOperation;
                    GDataBatchOperationClass;
enum                GDataBatchOperationType;
void                (*GDataBatchOperationCallback)      (guint operation_id,
                                                         GDataBatchOperationType operation_type,
                                                         GDataEntry *entry,
                                                         GError *error,
                                                         gpointer user_data);
guint               gdata_batch_operation_add_query     (GDataBatchOperation *self,
                                                         const gchar *id,
                                                         GType entry_type,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);
guint               gdata_batch_operation_add_insertion (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);
guint               gdata_batch_operation_add_update    (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);
guint               gdata_batch_operation_add_deletion  (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);
gboolean            gdata_batch_operation_run           (GDataBatchOperation *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_batch_operation_run_async     (GDataBatchOperation *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gdata_batch_operation_run_finish    (GDataBatchOperation *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);
GDataService *      gdata_batch_operation_get_service   (GDataBatchOperation *self);
GDataAuthorizationDomain * gdata_batch_operation_get_authorization_domain
                                                        (GDataBatchOperation *self);
const gchar *       gdata_batch_operation_get_feed_uri  (GDataBatchOperation *self);

Object Hierarchy

  GObject
   +----GDataBatchOperation

Properties

  "authorization-domain"     GDataAuthorizationDomain*  : Read / Write / Construct Only
  "feed-uri"                 gchar*                : Read / Write / Construct Only
  "service"                  GDataService*         : Read / Write / Construct Only

Description

GDataBatchOperation is a transient standalone class which represents and handles a single batch operation request to a service. To make a batch operation request: create a new GDataBatchOperation; add the required queries, insertions, updates and deletions to the operation using gdata_batch_operation_add_query(), gdata_batch_operation_add_insertion(), gdata_batch_operation_add_update() and gdata_batch_operation_add_deletion(), respectively; run the request with gdata_batch_operation_run() or gdata_batch_operation_run_async(); and handle the results in the callback functions which are invoked by the operation as the results are received and parsed.

If authorization is required for any of the requests in the batch operation, the GDataService set in "service" must have a GDataAuthorizer set as its "authorizer" property, and that authorizer must be authorized for the GDataAuthorizationDomain set in "authorization-domain". It's not possible for requests in a single batch operation to be authorized under multiple domains; in that case, the requests must be split up across several batch operations using different authorization domains.

If all of the requests in the batch operation don't require authorization (i.e. they all operate on public data; see the documentation for the GDataService subclass in question's operations for details of which require authorization), "authorization-domain" can be set to NULL to save the overhead of sending authorization data to the online service.

Example 5. Running a Synchronous Operation

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
42
43
44
45
guint op_id, op_id2;
GDataBatchOperation *operation;
GDataContactsContact *contact;
GDataService *service;
GDataAuthorizationDomain *domain;

service = create_contacts_service ();
domain = get_authorization_domain_from_service (service);
contact = create_new_contact ();
batch_link = gdata_feed_look_up_link (contacts_feed, GDATA_LINK_BATCH);

operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), domain, gdata_link_get_uri (batch_link));

/* Add to the operation to insert a new contact and query for another one */
op_id = gdata_batch_operation_add_insertion (operation, GDATA_ENTRY (contact), insertion_cb, user_data);
op_id2 = gdata_batch_operation_add_query (operation, gdata_entry_get_id (other_contact), GDATA_TYPE_CONTACTS_CONTACT, query_cb, user_data);

g_object_unref (contact);
g_object_unref (domain);
g_object_unref (service);

/* Run the operations in a blocking fashion. Ideally, check and free the error as appropriate after running the operation. */
gdata_batch_operation_run (operation, NULL, &error);

g_object_unref (operation);

static void
insertion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
{
    /* operation_id == op_id, operation_type == GDATA_BATCH_OPERATION_INSERTION */

    /* Process the new inserted entry, ideally after checking for errors. Note that the entry should be reffed if it needs to stay
     * alive after execution of the callback finishes. */
    process_inserted_entry (entry, user_data);
}

static void
query_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
{
    /* operation_id == op_id2, operation_type == GDATA_BATCH_OPERATION_QUERY */

    /* Process the results of the query, ideally after checking for errors. Note that the entry should be reffed if it needs to
     * stay alive after execution of the callback finishes. */
    process_queried_entry (entry, user_data);
}


Details

GDataBatchOperation

typedef struct _GDataBatchOperation GDataBatchOperation;

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

Since 0.7.0


GDataBatchOperationClass

typedef struct {
} GDataBatchOperationClass;

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

Since 0.7.0


enum GDataBatchOperationType

typedef enum {
	GDATA_BATCH_OPERATION_QUERY = 0,
	GDATA_BATCH_OPERATION_INSERTION,
	GDATA_BATCH_OPERATION_UPDATE,
	GDATA_BATCH_OPERATION_DELETION
} GDataBatchOperationType;

Indicates which type of batch operation caused the current GDataBatchOperationCallback to be called.

GDATA_BATCH_OPERATION_QUERY

a query operation

GDATA_BATCH_OPERATION_INSERTION

an insertion operation

GDATA_BATCH_OPERATION_UPDATE

an update operation

GDATA_BATCH_OPERATION_DELETION

a deletion operation

Since 0.7.0


GDataBatchOperationCallback ()

void                (*GDataBatchOperationCallback)      (guint operation_id,
                                                         GDataBatchOperationType operation_type,
                                                         GDataEntry *entry,
                                                         GError *error,
                                                         gpointer user_data);

Callback function called once for each operation in a batch operation run. The operation is identified by operation_id and operation_type (where operation_id is the ID returned by the relevant call to gdata_batch_operation_add_query(), gdata_batch_operation_add_insertion(), gdata_batch_operation_add_update() or gdata_batch_operation_add_deletion(), and operation_type shows which one of the above was called).

If the operation was successful, the resulting GDataEntry will be passed in as entry, and error will be NULL. Otherwise, entry will be NULL and a descriptive error will be in error. If operation_type is GDATA_BATCH_OPERATION_DELETION, entry will always be NULL, and error will be NULL or non-NULL as appropriate.

If the callback code needs to retain a copy of entry, it must be referenced (with g_object_ref()). Similarly, error is owned by the calling code, and must not be freed.

The callback is called in the main thread, and there is no guarantee on the order in which the callbacks for the operations in a run are executed, or whether they will be called in a timely manner. It is, however, guaranteed that they will all be called before the GAsyncReadyCallback which signals the completion of the run (if initiated with gdata_batch_operation_run_async()) is called; or gdata_batch_operation_run() returns (if initiated synchronously).

operation_id :

the operation ID returned from gdata_batch_operation_add_*()

operation_type :

the type of operation which was requested

entry :

the result of the operation, or NULL

error :

a GError describing any error which occurred, or NULL

user_data :

user data passed to the callback

Since 0.7.0


gdata_batch_operation_add_query ()

guint               gdata_batch_operation_add_query     (GDataBatchOperation *self,
                                                         const gchar *id,
                                                         GType entry_type,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);

Add a query to the GDataBatchOperation, to be executed when the operation is run. The query will return a GDataEntry (of subclass type entry_type) representing the given entry id. The ID is of the same format as that returned by gdata_entry_get_id().

Note that a single batch operation should not operate on a given GDataEntry more than once, as there's no guarantee about the order in which the batch operation's operations will be performed.

callback will be called when the GDataBatchOperation is run with gdata_batch_operation_run() (in which case it will be called in the thread which ran the batch operation), or with gdata_batch_operation_run_async() (in which case it will be called in an idle handler in the main thread). The operation_id passed to the callback will match the return value of gdata_batch_operation_add_query(), and the operation_type will be GDATA_BATCH_OPERATION_QUERY. If the query was successful, the resulting entry will be passed to the callback function as entry, and error will be NULL. If, however, the query was unsuccessful, entry will be NULL and error will contain a GError detailing what went wrong.

self :

a GDataBatchOperation

id :

the ID of the entry being queried for

entry_type :

the type of the entry which will be returned

callback :

a GDataBatchOperationCallback to call when the query is finished, or NULL. [scope async]

user_data :

data to pass to the callback function. [closure]

Returns :

operation ID for the added query, or 0

Since 0.7.0


gdata_batch_operation_add_insertion ()

guint               gdata_batch_operation_add_insertion (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);

Add an entry to the GDataBatchOperation, to be inserted on the server when the operation is run. The insertion will return the inserted version of entry. entry is reffed by the function, so may be freed after it returns.

callback will be called as specified in the documentation for gdata_batch_operation_add_query(), with an operation_type of GDATA_BATCH_OPERATION_INSERTION.

self :

a GDataBatchOperation

entry :

the GDataEntry to insert

callback :

a GDataBatchOperationCallback to call when the insertion is finished, or NULL. [scope async]

user_data :

data to pass to the callback function. [closure]

Returns :

operation ID for the added insertion, or 0

Since 0.7.0


gdata_batch_operation_add_update ()

guint               gdata_batch_operation_add_update    (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);

Add an entry to the GDataBatchOperation, to be updated on the server when the operation is run. The update will return the updated version of entry. entry is reffed by the function, so may be freed after it returns.

Note that a single batch operation should not operate on a given GDataEntry more than once, as there's no guarantee about the order in which the batch operation's operations will be performed.

callback will be called as specified in the documentation for gdata_batch_operation_add_query(), with an operation_type of GDATA_BATCH_OPERATION_UPDATE.

self :

a GDataBatchOperation

entry :

the GDataEntry to update

callback :

a GDataBatchOperationCallback to call when the update is finished, or NULL. [scope async]

user_data :

data to pass to the callback function. [closure]

Returns :

operation ID for the added update, or 0

Since 0.7.0


gdata_batch_operation_add_deletion ()

guint               gdata_batch_operation_add_deletion  (GDataBatchOperation *self,
                                                         GDataEntry *entry,
                                                         GDataBatchOperationCallback callback,
                                                         gpointer user_data);

Add an entry to the GDataBatchOperation, to be deleted on the server when the operation is run. entry is reffed by the function, so may be freed after it returns.

Note that a single batch operation should not operate on a given GDataEntry more than once, as there's no guarantee about the order in which the batch operation's operations will be performed.

callback will be called as specified in the documentation for gdata_batch_operation_add_query(), with an operation_type of GDATA_BATCH_OPERATION_DELETION.

self :

a GDataBatchOperation

entry :

the GDataEntry to delete

callback :

a GDataBatchOperationCallback to call when the deletion is finished, or NULL. [scope async]

user_data :

data to pass to the callback function. [closure]

Returns :

operation ID for the added deletion, or 0

Since 0.7.0


gdata_batch_operation_run ()

gboolean            gdata_batch_operation_run           (GDataBatchOperation *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

Run the GDataBatchOperation synchronously. This will send all the operations in the batch operation to the server, and call their respective callbacks synchronously (i.e. before gdata_batch_operation_run() returns, and in the same thread that called gdata_batch_operation_run()) as the server returns results for each operation.

The callbacks for all of the operations in the batch operation are always guaranteed to be called, even if the batch operation as a whole fails. Each callback will be called exactly once for each time gdata_batch_operation_run() is called.

The return value of the function indicates whether the overall batch operation was successful, and doesn't indicate the status of any of the operations it comprises. gdata_batch_operation_run() could return TRUE even if all of its operations failed.

cancellable can be used to cancel the entire batch operation any time before or during the network activity. If cancellable is cancelled after network activity has finished, gdata_batch_operation_run() will continue and finish as normal.

self :

a GDataBatchOperation

cancellable :

a GCancellable, or NULL. [allow-none]

error :

a GError, or NULL

Returns :

TRUE on success, FALSE otherwise

Since 0.7.0


gdata_batch_operation_run_async ()

void                gdata_batch_operation_run_async     (GDataBatchOperation *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Run the GDataBatchOperation asynchronously. This will send all the operations in the batch operation to the server, and call their respective callbacks asynchronously (i.e. in idle functions in the main thread, usually after gdata_batch_operation_run_async() has returned) as the server returns results for each operation. self is reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see gdata_batch_operation_run(), which is the synchronous version of this function.

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

self :

a GDataBatchOperation

cancellable :

a GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback to call when the batch operation is finished, or NULL

user_data :

data to pass to the callback function. [closure]

Since 0.7.0


gdata_batch_operation_run_finish ()

gboolean            gdata_batch_operation_run_finish    (GDataBatchOperation *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);

Finishes an asynchronous batch operation run with gdata_batch_operation_run_async().

Return values are as for gdata_batch_operation_run().

self :

a GDataBatchOperation

async_result :

a GAsyncResult

error :

a GError, or NULL

Returns :

TRUE on success, FALSE otherwise

Since 0.7.0


gdata_batch_operation_get_service ()

GDataService *      gdata_batch_operation_get_service   (GDataBatchOperation *self);

Gets the "service" property.

self :

a GDataBatchOperation

Returns :

the batch operation's attached service. [transfer none]

Since 0.7.0


gdata_batch_operation_get_authorization_domain ()

GDataAuthorizationDomain * gdata_batch_operation_get_authorization_domain
                                                        (GDataBatchOperation *self);

Gets the "authorization-domain" property.

self :

a GDataBatchOperation

Returns :

the GDataAuthorizationDomain used to authorize the batch operation, or NULL. [transfer none][allow-none]

Since 0.9.0


gdata_batch_operation_get_feed_uri ()

const gchar *       gdata_batch_operation_get_feed_uri  (GDataBatchOperation *self);

Gets the "feed-uri" property.

self :

a GDataBatchOperation

Returns :

the batch operation's feed URI

Since 0.7.0

Property Details

The "authorization-domain" property

  "authorization-domain"     GDataAuthorizationDomain*  : Read / Write / Construct Only

The authorization domain for the batch operation, against which the "authorizer" for the "service" should be authorized. This may be NULL if authorization is not needed for any of the requests in the batch operation.

All requests in the batch operation must be authorizable under this single authorization domain. If requests need different authorization domains, they must be performed in different batch operations.

Since 0.9.0


The "feed-uri" property

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

The feed URI that this batch operation will be sent to.

Default value: NULL

Since 0.7.0


The "service" property

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

The service this batch operation is attached to.

Since 0.7.0