1 /*

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Harvester client header

    15 *

    16 */

    17 

    18 

    19 #ifndef __HARVESTER_CLIENT_H__

    20 #define __HARVESTER_CLIENT_H__

    21 

    22 #include <e32base.h>

    23 

    24 #include <mdccommon.h>

    25 #include <mdeconstants.h>

    26 #include <harvestereventenum.h>

    27 

    28 // forward declarations

    29 class CHarvesterClientAO;

    30 class CHarvesterSessionAsyncHandler;

    31 class CHarvesterEventObserverAO;

    32 class MHarvesterEventObserver;

    33 class CHarvesterRequestActive;

    34 class CHarvesterRequestQueue;

    35 

    36 // default event interval for MHarvesterEventObserver

    37 const TInt KHarvesterEventInterval = 20;

    38 

    39 /**

    40  * Observer interface to inform when fast harvesting is completed

    41  * with the HarvestingComplete callback.

    42  *

    43  * Example of MHarvestObserver and RHarvesterClient::HarvestFile usage:

    44  *

    45  * Client application (like Camera) which wants to observe the completion of 

    46  * harvesting requests (issued with RHarvesterClient::Harvestile method) needs

    47  * implement the interface MHarvestObserver::HarvestingComplete. Callback 

    48  * HarvestingComplete provides the name of the harvested file (aURI) and also possible 

    49  * error code (aError).

    50  *

    51  * class CHarvestingObserver : public MHarvestObserver

    52  *     {

    53  *     void HarvestingComplete( TDesC& aURI, TInt aError ); // from MHarvestObserver

    54  *     void IssueHarvestingRequests();

    55  * 

    56  *     RHarvesterClient iHClient;	

    57  *     }

    58  *

    59  * void CHarvestObserver::ConstructL()

    60  *     {

    61  *     // connecting to Harvester server

    62  *	   iHClient.Connect();

    63  *     }

    64  * 

    65  * void CHarvestObserver::IssueHarvestingRequests()

    66  *     {

    67  *     // new harvesting request data

    68  * 	   _LIT( KNewFile, "C:\\Data\\ThisIsANewFile1.jpg" );

    69  *     RArray<TItemId> defaultPhotoAlbums;

    70  *	   defaultPhotoAlbums.Append( 123 );

    71  *     defaultPhotoAlbums.Append( 456 );

    72  *     defaultPhotoAlbums.Append( 789 );

    73  *

    74  *     // setting this class as the observer for the fast harvesting calls

    75  *      iHClient.SetObserver(this);

    76  *        

    77  *     // issué new harvesting request and requesting location data to be harvested

    78  *     iHClient.HarvestFile( KNewFile, defaultPhotoAlbums, ETrue );   

    79  *     }

    80  *

    81  * void CHarvestObserver::HarvestingComplete( TDesC& aURI, TInt aError )

    82  *     {

    83  *     _LIT( KExpectedFile, "C:\\Data\\ThisIsANewFile1.jpg" );

    84  *

    85  *     // Checking if an error occurred and if this was the expected file

    86  *     if ((aError == KErrNone) && (aURI.CompareC(KExpectedFile) == 0))

    87  *         {

    88  *         // do something

    89  *         }

    90  *     }

    91  *

    92  */

    93 class MHarvestObserver

    94 	{

    95 public:

    96     /**

    97      * Callback to inform when fast harvesting of a file is complete.

    98      * 

    99      * @param aURI    URI of the harvested file.

   100      * @param aError  Error code of the fast harvesting. <code>KErrNone</code> is

   101      *                expected if fast harvesting succeeded. Otherwise some

   102      *                system wide error code. 

   103      *

   104      */

   105 	virtual void HarvestingComplete( TDesC& aURI, TInt aError ) = 0;

   106 	};

   107 

   108 /**

   109  * Observer interface to inform about events that happen inside the observer framework

   110  *

   111  * Example of MHarvesterEventObserver, RHarvesterClient::AddHarvesterEventObserver and

   112  * RHarvesterClient::RemoveHarvesterEventObserver usage:

   113  *

   114  * void CHarvestObserver::ConstructL()

   115  *     {

   116  *     // iHClient is instance of RHarvesterClient

   117  *	   iHClient.Connect();

   118  *

   119  *     // Listen to placeholder changes to "full" metadata objects - request notification

   120  *     // after 100 items have changed.

   121  *     TInt err = iHClient.AddHarvesterEventObserver( *this, EHEObserverTypePlaceholder, 100 );

   122  *     if (err == KErrNone)

   123  *         {

   124  *         // do something now that event observer is setup

   125  *         }

   126  *     }

   127  *

   128  * void CHarvestObserver::HarvestingUpdated( HarvesterEventObserverType aHEObserverType, 

   129  *			HarvesterEventState aHarvesterEventState, TInt aItemsLeft )

   130  *     {

   131  *     // Check the observer notification type

   132  *     if (aHEObserverType == EHEObserverTypePlaceholder)

   133  *         {

   134  *         // Checking if there are more than 1000 items left to process 

   135  *         if (aItemsLeft > 1000)

   136  *             {

   137  *             // do something since there are some many items still placeholders

   138  *             }

   139  *         if (aItemsLeft == 0)

   140  *             {

   141 	           // all placeholders changed to "full" objects - do something...

   142  *             }

   143  *         }   

   144  *     }

   145  *

   146  * CHarvestObserver::~CHarvestObserver()

   147  *     {

   148  *     // Removing the observer in destructor

   149  *     iHClient.RemoveHarvesterEventObserver( *this );   

   150  *     }

   151  */

   152 

   153 

   154 class MHarvesterEventObserver

   155 	{

   156 public:

   157     /**

   158      * Callback interface which informs about harvesting changes based on the observers

   159      * that the end user has setup/registered.

   160      * 

   161      * @param aHEObserverType       Defines the observer type to which this events is related 

   162      * @param aHarvesterEventState  Event that occurred

   163      * @param aItemsLeft            Number of items left regarding the harvesting procedure (defined

   164      *                              by aHEObserverType)

   165      * @see RHarvesterClient::AddHarvesterEventObserver

   166      * @see RHarvesterClient::RemoveHarvesterEventObserver

   167      */

   168 	virtual void HarvestingUpdated( 

   169 			HarvesterEventObserverType aHEObserverType, 

   170 			HarvesterEventState aHarvesterEventState,

   171 			TInt aItemsLeft ) = 0;

   172 	};

   173 

   174 /**

   175  * Harvester client session class which provides also means to:

   176  * - Pause/resume the Harvesting framework

   177  * - Fast harvest files and observe when they have been harvested

   178  * - Setup observers to observe the harvesting progress

   179  */

   180 NONSHARABLE_CLASS( RHarvesterClient ) : public RSessionBase

   181 	{

   182 	friend class CHarvesterSessionAsyncHandler;

   183 	friend class CHarvesterEventObserverAO;

   184 

   185 	public:

   186 		

   187         /**

   188          * Constructor

   189          */

   190         IMPORT_C RHarvesterClient();

   191 

   192         /**

   193          * Public method to connect Harvester server.

   194          * 

   195          * @return Symbian OS error code.

   196          */

   197         IMPORT_C TInt Connect();

   198          

   199         /**

   200          * Public method to pause the operation

   201          * of the Harvester framework.

   202          *

   203          * @return  Symbian OS error code.

   204          */

   205         IMPORT_C TInt Pause();

   206 

   207         /**

   208          * Public method to resume the operation

   209          * of the Harvester framework.

   210          *

   211          * @return  Symbian OS error code.

   212          */    

   213         IMPORT_C TInt Resume();

   214 

   215         /**

   216          * Public method to close session to Harvester server.

   217          */

   218         IMPORT_C void Close();

   219             

   220         /**

   221          * Public method to set observer for fast harvesting.

   222          * Only one observer is currently supported.

   223          *

   224          * @param aObserver  Pointer to the observer

   225          */     

   226         IMPORT_C void SetObserver( MHarvestObserver* aObserver);

   227 

   228         /**

   229          * Public method to remove observer for fast harvesting.

   230          *

   231          * @param aObserver  Pointer to the observer

   232          */     

   233         IMPORT_C void RemoveObserver( MHarvestObserver* aObserver);

   234         

   235         /**

   236          * Public method for doing fast harvesting. These files

   237          * are handled first before the ones that are in the harvesting 

   238          * queue inside the Harvesting framework.

   239          *

   240          * @param aURI          Uri of the file to be harvested

   241          * @param aAlbumIds     Array of album id's that the harvested file 

   242          *                      will be included in

   243          * @param aAddLocation  Should location information be added to item

   244          */ 

   245     	IMPORT_C void HarvestFile( const TDesC& aURI, RArray<TItemId> &aAlbumIds, TBool aAddLocation );

   246         

   247         /**

   248          * Method for adding observer for harvester framework events

   249          *

   250          * @param aHarvesterEventObserver  class to implement MHarvesterEventObserver interface

   251          * @param aHEObserverType          Harvester event observer type (EPlaceholderState, 

   252          *                                 EMMCState, EOverallState)

   253          * @param aEventInterval           Interval of harvester events as item amount

   254          * 

   255          * @return  Symbian OS wide error code.

   256          */

   257         IMPORT_C TInt AddHarvesterEventObserver( 

   258         		MHarvesterEventObserver& aHarvesterEventObserver, 

   259         		TInt aHEObserverType,

   260         		TInt aEventInterval = KHarvesterEventInterval );

   261         

   262         /**

   263          * Method for removing observer for harvester framework events. Please note that

   264          * removing any of the event observers will remove all observers which are registered

   265          * by the given parameter aHarvesterEventObserver (= observer class).

   266          *

   267          * @param aHarvesterEventObserver class to implement MHarvesterEventObserver interface

   268          *

   269          * @return  Symbian OS wide error code.

   270          */

   271         IMPORT_C TInt RemoveHarvesterEventObserver( MHarvesterEventObserver& aHarvesterEventObserver );

   272         

   273 		/**

   274          * Public method for doing fast harvesting. These files

   275          * are handled first before the ones that are in the harvesting 

   276          * queue. 

   277          *

   278          * @param aURI          Uri of the file to be harvested

   279          * @param aAlbumIds     Array of album id's that the harvested file will be included in

   280          * @param aAddLocation  Should location information be added to image

   281 		 * @param aUid          Uid of the originating application for the object

   282          */ 

   283     	IMPORT_C void HarvestFileWithUID( const TDesC& aURI, 

   284 		                                  RArray<TItemId> &aAlbumIds, 

   285 										  TBool aAddLocation,

   286 										  TUid aUid );

   287 		

   288         /**

   289          * Requests a harvest complete event from harvester server.

   290 		 * On return, aURI is the URI of the harvested file.

   291          *

   292          * @param aURI  Harvested image uri what server

   293          * @param aStatus    Reference to a request indicator

   294          */ 

   295         void RegisterHarvestComplete( TDes& aURI, TRequestStatus& aStatus );

   296         

   297         /**

   298          * Cancels the harvest complete notification request.

   299          */ 

   300         void UnregisterHarvestComplete( );

   301         

   302         /**

   303          * Private method for doing fast harvesting. These files

   304          * are handled first before the ones that are in the harvesting 

   305          * queue.

   306          * 

   307          * @param aService  Service request which to execute on server side

   308          * @param aArgs     Parameters for harvesting

   309          * @param aStatus   Status of the asunchronous call

   310          */ 

   311         void HarvestFile( TInt& aService, TIpcArgs& aArgs, TRequestStatus& aStatus  );

   312 

   313         /**

   314          * Restricted method for doing fast harvesting. These files

   315          * are handled first before the ones that are in the harvesting 

   316          * queue. This version forces the file to be harvested immidiately.

   317          * 

   318          * @param aService  Service request which to execute on server side

   319          * @param aArgs     Parameters for harvesting

   320          */ 

   321         void ForceHarvestFile( TInt& aService, TIpcArgs& aArgs );

   322         

   323 	private: 

   324 

   325 	    /**

   326 	     * Observer of the class

   327 	     */ 

   328 	     MHarvestObserver* iObserver;

   329 	

   330         /**

   331          * Private method for version.

   332          */      

   333         TVersion Version() const;

   334 

   335         /**

   336          * Harvester client active object.

   337          */    

   338         CHarvesterClientAO* iHarvesterClientAO;

   339         

   340         /** 

   341          * Pointer to Harvester event observer active object.

   342          */

   343         CHarvesterEventObserverAO* iHEO;

   344         

   345         /**

   346          * Request queue processor.

   347          */

   348         CHarvesterRequestQueue* iRequestQueue;

   349     	};

   350 

   351 #endif // __HARVESTER_CLIENT_H__