| Top |  |
 |
 |
 |
Functions
Properties
| GDataAuthorizationDomain * | authorization-domain | Read / Write / Construct Only |
| gchar * | feed-uri | Read / Write / Construct Only |
| GDataService * | service | 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); } |
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).
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 |
||
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 |
[scope async] |
user_data |
data to pass to the |
[closure] |
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 |
||
entry |
the GDataEntry to insert |
|
callback |
a GDataBatchOperationCallback to call when the insertion is finished, or |
[scope async] |
user_data |
data to pass to the |
[closure] |
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 |
||
entry |
the GDataEntry to update |
|
callback |
a GDataBatchOperationCallback to call when the update is finished, or |
[scope async] |
user_data |
data to pass to the |
[closure] |
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 |
||
entry |
the GDataEntry to delete |
|
callback |
a GDataBatchOperationCallback to call when the deletion is finished, or |
[scope async] |
user_data |
data to pass to the |
[closure] |
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.
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
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().
Since: 0.7.0
gdata_batch_operation_get_service ()
GDataService *
gdata_batch_operation_get_service (GDataBatchOperation *self);
Gets the “service” property.
Since: 0.7.0
gdata_batch_operation_get_authorization_domain ()
GDataAuthorizationDomain *
gdata_batch_operation_get_authorization_domain
(GDataBatchOperation *self);
Gets the “authorization-domain” property.
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.
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.
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