GData Reference Manual: GDataBatchOperation

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