Akonadi.ItemModifyJob

KDE 4.7 PyKDE API Reference

- KDE's Python API

# ItemModifyJob Class Reference

`from PyKDE4.akonadi import *`

Inherits: Akonadi.Job → KCompositeJob → KJob → QObject
Namespace: Akonadi

## Detailed Description

Job that modifies an existing item in the Akonadi storage.

This job is used to writing back items to the Akonadi storage, after the user has changed them in any way. For performance reasons either the full item (including the full payload) can written back or only the meta data of the item.

Example:

     // Fetch item with unique id 125
     Akonadi.ItemFetchJob *fetchJob = new Akonadi.ItemFetchJob( Akonadi.Item( 125 ) );
     connect( fetchJob, SIGNAL( result( KJob* ) ), SLOT( fetchFinished( KJob* ) ) );

     ...

     MyClass.fetchFinished( KJob *job )
     {
       if ( job->error() )
         return;

       Akonadi.ItemFetchJob *fetchJob = qobject_cast<Akonadi.ItemFetchJob*>( job );

       Akonadi.Item item = fetchJob->items().first();

       // Set a custom flag
       item.setFlag( "\GotIt" );

       // Store back modified item
       Akonadi.ItemModifyJob *modifyJob = new Akonadi.ItemModifyJob( item );
       connect( modifyJob, SIGNAL( result( KJob* ) ), SLOT( modifyFinished( KJob* ) ) );
     }

     MyClass.modifyFinished( KJob *job )
     {
       if ( job->error() )
         qDebug() << "Error occurred";
       else
         qDebug() << "Item modified successfully";
     }

<h3>Conflict Resolution</h3>

When the job is executed, a check is made to ensure that the Item contained in the job is not older than the version of the Item already held in the Akonadi database. If it is older, a conflict resolution dialog is displayed for the user to choose which version of the Item to use, unless disableAutomaticConflictHandling() has been called to disable the dialog, or disableRevisionCheck() has been called to disable version checking altogether.

The item version is checked by comparing the Item.revision() values in the job and in the database. To ensure that two successive ItemModifyJobs for the same Item work correctly, the revision number of the Item supplied to the second ItemModifyJob should be set equal to the Item's revision number on completion of the first ItemModifyJob. This can be obtained by, for example, calling item().revision() in the job's result slot.

Author:
  Volker Krause <vkrause@kde.org>

## Methods
| __init__ (self, Akonadi.Item item, QObject parent=0)
| __init__ (self, [Akonadi.Item] items, QObject parent=0)
| disableAutomaticConflictHandling (self)
| disableRevisionCheck (self)
| doHandleResponse (self, QByteArray tag, QByteArray data)
| doStart (self)
bool | ignorePayload (self)
Akonadi.Item | item (self)
[Akonadi.Item] | items (self)
| setIgnorePayload (self, bool ignore)

## Method Documentation

__init__ | ( | self, |
|  | Akonadi.Item | item,
|  | QObject | parent=0
| ) |  |  |

Creates a new item modify job.

Parameters:

  | item | The modified item object to store.
  | parent | The parent object.

__init__ | ( | self, |
|  | [Akonadi.Item] | items,
|  | QObject | parent=0
| ) |  |  |

Creates a new item modify job for bulk modifications.

Using this is different from running a modification job per item. Use this when applying the same change to a set of items, such as a mass-change of item flags, not if you just want to store a bunch of randomly modified items.

Currently the following modifications are supported: - flag changes

Note:
  Since this does not do payload modifications, it implies setIgnorePayload( true ) and disableRevisionCheck().

Parameters:

  | items | The list of items to modify, must not be empty.

Since:
  4.6

disableAutomaticConflictHandling | ( |  | self ) |

Disables the automatic handling of conflicts.

By default the item modify job will bring up a dialog to resolve a conflict that might happen when modifying an item. Calling this method will avoid that and the job returns with an error in case of a conflict.

Since:
  4.6

disableRevisionCheck | ( |  | self ) |

Disables the check of the revision number.

Note:
  If disabled, no conflict detection is available.

doHandleResponse | ( | self, |
|  | QByteArray | tag,
|  | QByteArray | data
| ) |  |  |

doStart | ( |  | self ) |

bool ignorePayload | ( |  | self ) |

Returns whether the payload of the modified item shall be omitted from transmission to the Akonadi storage.

Akonadi.Item item | ( |  | self ) |

Returns the modified and stored item including the changed revision number.

Note:
  Use this method only when using the single item constructor.

[Akonadi.Item] items | ( |  | self ) |

Returns the modified and stored items including the changed revision number.

Since:
  4.6

setIgnorePayload | ( | self, |
|  | bool | ignore
| ) |  |  |

Sets whether the payload of the modified item shall be omitted from transmission to the Akonadi storage. The default is false, however it can be set for performance reasons.