GDataBatchOperation

GDataBatchOperation — GData batch operation object

Stability Level

Stable, unless otherwise indicated

Properties

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

Object Hierarchy

    GObject
    ╰── GDataBatchOperation

Includes

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

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);
}


Functions

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

Returns

the batch operation's feed URI

Since 0.7.0

Types and Values

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

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

Members

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

Property Details

The “authorization-domain” property

  “authorization-domain”     GDataAuthorizationDomain *

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.

Flags: Read / Write / Construct Only

Since 0.9.0


The “feed-uri” property

  “feed-uri”                 gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Since 0.7.0


The “service” property

  “service”                  GDataService *

The service this batch operation is attached to.

Flags: Read / Write / Construct Only

Since 0.7.0