• Skip to content
  • Skip to link menu
KDE 4.6 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • KDE Home
  • Contact Us
 

akonadi

  • Akonadi
  • ItemModifyJob
Public Member Functions | Protected Member Functions
Akonadi::ItemModifyJob Class Reference

Job that modifies an existing item in the Akonadi storage. More...

#include <itemmodifyjob.h>

Inheritance diagram for Akonadi::ItemModifyJob:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 ItemModifyJob (const Item &item, QObject *parent=0)
 ItemModifyJob (const Item::List &items, QObject *parent=0)
virtual ~ItemModifyJob ()
void disableAutomaticConflictHandling ()
void disableRevisionCheck ()
bool ignorePayload () const
Item item () const
Item::List items () const
void setIgnorePayload (bool ignore)

Protected Member Functions

virtual void doHandleResponse (const QByteArray &tag, const QByteArray &data)
virtual void doStart ()

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

Conflict Resolution

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>

Definition at line 97 of file itemmodifyjob.h.


Constructor & Destructor Documentation

Akonadi::ItemModifyJob::ItemModifyJob ( const Item &  item,
QObject *  parent = 0 
) [explicit]

Creates a new item modify job.

Parameters:
itemThe modified item object to store.
parentThe parent object.
Akonadi::ItemModifyJob::ItemModifyJob ( const Item::List &  items,
QObject *  parent = 0 
) [explicit]

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:
itemsThe list of items to modify, must not be empty.
Since:
4.6
ItemModifyJob::~ItemModifyJob ( ) [virtual]

Destroys the item modify job.

Definition at line 132 of file itemmodifyjob.cpp.


Member Function Documentation

void ItemModifyJob::disableAutomaticConflictHandling ( )

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

Definition at line 329 of file itemmodifyjob.cpp.

void ItemModifyJob::disableRevisionCheck ( )

Disables the check of the revision number.

Note:
If disabled, no conflict detection is available.

Definition at line 322 of file itemmodifyjob.cpp.

virtual void Akonadi::ItemModifyJob::doHandleResponse ( const QByteArray &  tag,
const QByteArray &  data 
) [protected, virtual]

This method should be reimplemented in the concrete jobs in case you want to handle incoming data.

It will be called on received data from the backend. The default implementation does nothing.

Parameters:
tagThe tag of the corresponding command, empty if this is an untagged response.
dataThe received data.

Reimplemented from Akonadi::Job.

virtual void Akonadi::ItemModifyJob::doStart ( ) [protected, virtual]

This method must be reimplemented in the concrete jobs.

It will be called after the job has been started and a connection to the Akonadi backend has been established.

Implements Akonadi::Job.

bool ItemModifyJob::ignorePayload ( ) const

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

Definition at line 315 of file itemmodifyjob.cpp.

Item Akonadi::ItemModifyJob::item ( ) const

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

Note:
Use this method only when using the single item constructor.
Item::List Akonadi::ItemModifyJob::items ( ) const

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

Since:
4.6
void ItemModifyJob::setIgnorePayload ( 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.

Definition at line 299 of file itemmodifyjob.cpp.


The documentation for this class was generated from the following files:
  • itemmodifyjob.h
  • itemmodifyjob.cpp

akonadi

Skip menu "akonadi"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.7.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal