/*
* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Harvester client header
*
*/
#ifndef __HARVESTER_CLIENT_H__
#define __HARVESTER_CLIENT_H__
#include <e32base.h>
#include <mdccommon.h>
#include <mdeconstants.h>
#include <harvestereventenum.h>
// forward declarations
class CHarvesterClientAO;
class CHarvesterSessionAsyncHandler;
class CHarvesterEventObserverAO;
class MHarvesterEventObserver;
class CHarvesterRequestActive;
class CHarvesterRequestQueue;
// default event interval for MHarvesterEventObserver
const TInt KHarvesterEventInterval = 20;
/**
* Observer interface to inform when fast harvesting is completed
* with the HarvestingComplete callback.
*
* Example of MHarvestObserver and RHarvesterClient::HarvestFile usage:
*
* Client application (like Camera) which wants to observe the completion of
* harvesting requests (issued with RHarvesterClient::Harvestile method) needs
* implement the interface MHarvestObserver::HarvestingComplete. Callback
* HarvestingComplete provides the name of the harvested file (aURI) and also possible
* error code (aError).
*
* class CHarvestingObserver : public MHarvestObserver
* {
* void HarvestingComplete( TDesC& aURI, TInt aError ); // from MHarvestObserver
* void IssueHarvestingRequests();
*
* RHarvesterClient iHClient;
* }
*
* void CHarvestObserver::ConstructL()
* {
* // connecting to Harvester server
* iHClient.Connect();
* }
*
* void CHarvestObserver::IssueHarvestingRequests()
* {
* // new harvesting request data
* _LIT( KNewFile, "C:\\Data\\ThisIsANewFile1.jpg" );
* RArray<TItemId> defaultPhotoAlbums;
* defaultPhotoAlbums.Append( 123 );
* defaultPhotoAlbums.Append( 456 );
* defaultPhotoAlbums.Append( 789 );
*
* // setting this class as the observer for the fast harvesting calls
* iHClient.SetObserver(this);
*
* // issué new harvesting request and requesting location data to be harvested
* iHClient.HarvestFile( KNewFile, defaultPhotoAlbums, ETrue );
* }
*
* void CHarvestObserver::HarvestingComplete( TDesC& aURI, TInt aError )
* {
* _LIT( KExpectedFile, "C:\\Data\\ThisIsANewFile1.jpg" );
*
* // Checking if an error occurred and if this was the expected file
* if ((aError == KErrNone) && (aURI.CompareC(KExpectedFile) == 0))
* {
* // do something
* }
* }
*
*/
class MHarvestObserver
{
public:
/**
* Callback to inform when fast harvesting of a file is complete.
*
* @param aURI URI of the harvested file.
* @param aError Error code of the fast harvesting. <code>KErrNone</code> is
* expected if fast harvesting succeeded. Otherwise some
* system wide error code.
*
*/
virtual void HarvestingComplete( TDesC& aURI, TInt aError ) = 0;
};
/**
* Observer interface to inform about events that happen inside the observer framework
*
* Example of MHarvesterEventObserver, RHarvesterClient::AddHarvesterEventObserver and
* RHarvesterClient::RemoveHarvesterEventObserver usage:
*
* void CHarvestObserver::ConstructL()
* {
* // iHClient is instance of RHarvesterClient
* iHClient.Connect();
*
* // Listen to placeholder changes to "full" metadata objects - request notification
* // after 100 items have changed.
* TInt err = iHClient.AddHarvesterEventObserver( *this, EHEObserverTypePlaceholder, 100 );
* if (err == KErrNone)
* {
* // do something now that event observer is setup
* }
* }
*
* void CHarvestObserver::HarvestingUpdated( HarvesterEventObserverType aHEObserverType,
* HarvesterEventState aHarvesterEventState, TInt aItemsLeft )
* {
* // Check the observer notification type
* if (aHEObserverType == EHEObserverTypePlaceholder)
* {
* // Checking if there are more than 1000 items left to process
* if (aItemsLeft > 1000)
* {
* // do something since there are some many items still placeholders
* }
* if (aItemsLeft == 0)
* {
// all placeholders changed to "full" objects - do something...
* }
* }
* }
*
* CHarvestObserver::~CHarvestObserver()
* {
* // Removing the observer in destructor
* iHClient.RemoveHarvesterEventObserver( *this );
* }
*/
class MHarvesterEventObserver
{
public:
/**
* Callback interface which informs about harvesting changes based on the observers
* that the end user has setup/registered.
*
* @param aHEObserverType Defines the observer type to which this events is related
* @param aHarvesterEventState Event that occurred
* @param aItemsLeft Number of items left regarding the harvesting procedure (defined
* by aHEObserverType)
* @see RHarvesterClient::AddHarvesterEventObserver
* @see RHarvesterClient::RemoveHarvesterEventObserver
*/
virtual void HarvestingUpdated(
HarvesterEventObserverType aHEObserverType,
HarvesterEventState aHarvesterEventState,
TInt aItemsLeft ) = 0;
};
/**
* Harvester client session class which provides also means to:
* - Pause/resume the Harvesting framework
* - Fast harvest files and observe when they have been harvested
* - Setup observers to observe the harvesting progress
*/
NONSHARABLE_CLASS( RHarvesterClient ) : public RSessionBase
{
friend class CHarvesterSessionAsyncHandler;
friend class CHarvesterEventObserverAO;
public:
/**
* Constructor
*/
IMPORT_C RHarvesterClient();
/**
* Public method to connect Harvester server.
*
* @return Symbian OS error code.
*/
IMPORT_C TInt Connect();
/**
* Public method to pause the operation
* of the Harvester framework.
*
* @return Symbian OS error code.
*/
IMPORT_C TInt Pause();
/**
* Public method to resume the operation
* of the Harvester framework.
*
* @return Symbian OS error code.
*/
IMPORT_C TInt Resume();
/**
* Public method to close session to Harvester server.
*/
IMPORT_C void Close();
/**
* Public method to set observer for fast harvesting.
* Only one observer is currently supported.
*
* @param aObserver Pointer to the observer
*/
IMPORT_C void SetObserver( MHarvestObserver* aObserver);
/**
* Public method to remove observer for fast harvesting.
*
* @param aObserver Pointer to the observer
*/
IMPORT_C void RemoveObserver( MHarvestObserver* aObserver);
/**
* Public method for doing fast harvesting. These files
* are handled first before the ones that are in the harvesting
* queue inside the Harvesting framework.
*
* @param aURI Uri of the file to be harvested
* @param aAlbumIds Array of album id's that the harvested file
* will be included in
* @param aAddLocation Should location information be added to item
*/
IMPORT_C void HarvestFile( const TDesC& aURI, RArray<TItemId> &aAlbumIds, TBool aAddLocation );
/**
* Method for adding observer for harvester framework events
*
* @param aHarvesterEventObserver class to implement MHarvesterEventObserver interface
* @param aHEObserverType Harvester event observer type (EPlaceholderState,
* EMMCState, EOverallState)
* @param aEventInterval Interval of harvester events as item amount
*
* @return Symbian OS wide error code.
*/
IMPORT_C TInt AddHarvesterEventObserver(
MHarvesterEventObserver& aHarvesterEventObserver,
TInt aHEObserverType,
TInt aEventInterval = KHarvesterEventInterval );
/**
* Method for removing observer for harvester framework events. Please note that
* removing any of the event observers will remove all observers which are registered
* by the given parameter aHarvesterEventObserver (= observer class).
*
* @param aHarvesterEventObserver class to implement MHarvesterEventObserver interface
*
* @return Symbian OS wide error code.
*/
IMPORT_C TInt RemoveHarvesterEventObserver( MHarvesterEventObserver& aHarvesterEventObserver );
/**
* Public method for doing fast harvesting. These files
* are handled first before the ones that are in the harvesting
* queue.
*
* @param aURI Uri of the file to be harvested
* @param aAlbumIds Array of album id's that the harvested file will be included in
* @param aAddLocation Should location information be added to image
* @param aUid Uid of the originating application for the object
*/
IMPORT_C void HarvestFileWithUID( const TDesC& aURI,
RArray<TItemId> &aAlbumIds,
TBool aAddLocation,
TUid aUid );
/**
* Requests a harvest complete event from harvester server.
* On return, aURI is the URI of the harvested file.
*
* @param aURI Harvested image uri what server
* @param aStatus Reference to a request indicator
*/
void RegisterHarvestComplete( TDes& aURI, TRequestStatus& aStatus );
/**
* Cancels the harvest complete notification request.
*/
void UnregisterHarvestComplete( );
/**
* Private method for doing fast harvesting. These files
* are handled first before the ones that are in the harvesting
* queue.
*
* @param aService Service request which to execute on server side
* @param aArgs Parameters for harvesting
* @param aStatus Status of the asunchronous call
*/
void HarvestFile( TInt& aService, TIpcArgs& aArgs, TRequestStatus& aStatus );
/**
* Restricted method for doing fast harvesting. These files
* are handled first before the ones that are in the harvesting
* queue. This version forces the file to be harvested immidiately.
*
* @param aService Service request which to execute on server side
* @param aArgs Parameters for harvesting
*/
void ForceHarvestFile( TInt& aService, TIpcArgs& aArgs );
private:
/**
* Observer of the class
*/
MHarvestObserver* iObserver;
/**
* Private method for version.
*/
TVersion Version() const;
/**
* Harvester client active object.
*/
CHarvesterClientAO* iHarvesterClientAO;
/**
* Pointer to Harvester event observer active object.
*/
CHarvesterEventObserverAO* iHEO;
/**
* Request queue processor.
*/
CHarvesterRequestQueue* iRequestQueue;
};
#endif // __HARVESTER_CLIENT_H__