--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mds_plat/harvester_framework_api/inc/harvesterclient.h Mon Jan 18 20:34:07 2010 +0200
@@ -0,0 +1,351 @@
+/*
+* 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__