/*
* Copyright (c) 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:
*
*/
#ifndef SAMPLERPLUGINLOADER_H
#define SAMPLERPLUGINLOADER_H
// INCLUDES
#include <e32base.h>
#include <Ecom/ImplementationInformation.h>
#include <piprofiler/ProfilerConfig.h>
#include <piprofiler/SamplerPluginInterface.h>
// CONSTANTS
// Value for a to b comparison result when logically a == b.
const TInt KSamplerComparisonEqual = 0;
// Value for a to b comparison result when logically a < b.
const TInt KSamplerComparisonBefore = -1;
// Value for a to b comparison result when logically a > b.
const TInt KSamplerComparisonAfter = 1;
// CLASS DEFINITIONS
class CSamplerPluginInterface;
class MSamplerPluginLoadObserver;
class REComSession;
/**
* CSamplerPluginLoader. Mechanism used to load plugins asynchronously. Uses
* MSamplerPluginLoadObserver as a callback.
*
* @lib ProfilerEngine.exe/.lib???????????
* @since Series60_30.1
*/
class CSamplerPluginLoader : public CActive
{
public: // Constructor and destructor
/**
* Two-phased constructor.
*
* @param aAppUi Pointer to application UI. Does not take ownership.
*/
static CSamplerPluginLoader* NewL();
/**
* Destructor
*/
~CSamplerPluginLoader();
private: // Internal construction
/**
* Default C++ contructor
*/
CSamplerPluginLoader();
/**
* Symbian OS default constructor
* @return void
*/
void ConstructL();
public: // API
/**
* Starts loading GS plug-ins asynchronously. Will call
* MSamplerPluginLoadObserver::HandlePluginLoaded() each time a plug-in is
* loaded and when all plugins are loaded.
*
* CSamplerPluginLoader transfers the ownership of each loaded plugin view to
* CAknViewAppUi. It is client's responsibility to remove the views from
* CAknViewAppUi and delete the plugins if necessary.
*
* @param aInterfaceUid Uid ofthe interfaces to be loaded.
* @param aParentUid Uid of the parent. Only children of this parent
* will be loaded.
* @param aPluginArray An array for the loaded GS plug-ins.
* CSamplerPluginLoader does not take the ownership of this array.
*/
void LoadAsyncL( CArrayPtrFlat<CSamplerPluginInterface>* aPluginArray );
/**
* Load a specific plugin instance synchronously.
*
* @param aInterfaceUid Uid ofthe interfaces to be loaded.
* @param aImplementationUid Uid of the implementation to load
*/
void LoadSyncL( CArrayPtrFlat<CSamplerPluginInterface>* aPluginArray );
/**
* Sets observer for this loader. Only one observer per loader in one
* time is possible.
*/
void SetObserver(MSamplerPluginLoadObserver* aObserver);
/**
* Aborts asynchronous loading of the GS plug-ins.
*/
void AbortAsyncLoad();
/**
* Sorts the plugin array.
*
* Sorting criterias:
*
* 1. Order number if provider category is Internal.
* 2. Provider category. Precedence as follows:
* 1. KGSPluginProviderInternal
* 2. EGSPluginProviderOEM
* 3. EGSPluginProviderOperator
* 4. EGSPluginProvider3rdParty
* 3. Alphabetical
*
* @param aPlugins The array which will be sorted.
*/
void SortPluginsL( CArrayPtrFlat<CSamplerPluginInterface>* aPlugins );
private: // Internal methods
/**
* Starts loading next plugin.
*/
void LoadNextPluginL();
/**
* Creates a plugin instance from given UID. Ownership is transferred.
*/
CSamplerPluginInterface& CreatePluginInstanceL(
const CImplementationInformation& aImpInfo );
/**
* Notifies MPluginLoadObserver.
*/
void NotifyProgress();
/**
* Notifies MPluginLoadObserver.
*/
void NotifyFinished();
/**
* Wait for the next round of CActive execution.
*/
void CompleteOwnRequest();
// Insertion function used by sorting:
/**
* Inserts plugin in the correct position in the array using sorting
* criterias. Assumes aPlugins is ordered.
*
* @param aPlugin The plugin to be inserted.
* @param aPlugins Array in which the plugin is inserted into the
* corresponding location.
*/
void InsertPluginInOrderL(
CSamplerPluginInterface* aPlugin,
CArrayPtrFlat<CSamplerPluginInterface>* aPlugins );
// Comparison functions:
/**
* Compares plugins according to comparison criterias.
*
* Note: GS internal comparison constants such as KGSComparisonEqual are
* different from the ones outputted by this function. This is because
* this function is also usable by RArray sort -functionality but BC
* cannot be broken in GS.
*
* @return Negative value: If aFirst before aSecond.
* 0: If equal.
* Positive value: If aSecond before aFirst.
*/
static TInt Compare( const CSamplerPluginInterface& aFirst,
const CSamplerPluginInterface& aSecond );
/**
*
* @return KGSComparisonEqual = equal indexes
* KGSComparisonBefore = aFirst is before aSecond
* KGSComparisonAfter = aFirst is after aSecond
*/
static TInt CompareIndex(
const CSamplerPluginInterface& aFirst,
const CSamplerPluginInterface& aSecond );
private: // Utility methods
/**
* Parses descriptor to UID.
*/
static TInt ParseToUid( const TDesC8& aSource, TUid& aTarget );
/**
* Parsers plugin's order number
*/
static TInt ParseOrderNumber( const TDesC8& aSource, TInt& aOrderNumber );
/**
* Print ordering debug data.
*/
void CSamplerPluginLoader::PrintOrderTraces(
CArrayPtrFlat<CSamplerPluginInterface>* aPlugins );
private: // From CActive
/**
* See base class.
*/
void RunL();
/**
* See base class.
*/
TInt RunError( TInt aError );
/**
* See base class.
*/
void DoCancel();
private: // Data
// Pluginloader goes through this array and loads the plugins into
// iPluginArray if they fulfill the criterias.
RImplInfoPtrArray iImplInfoArray;
// Used as an iterator to maintain location in iImplInfoArray.
TInt iImplInfoArrayIterator;
// Array of loaded plugins.Plugins are owned by iAppUi. Only the array
// pointers are owned by this class and therefore only reset array.
CArrayPtrFlat<CSamplerPluginInterface>* iPluginArray;
// Pointer to observer. Not owned.
MSamplerPluginLoadObserver* iObserver;
// Number of RunL calls.
TInt iRunLDebugCount;
};
/**
* Interface for SamplerPluginLoader observer. MSamplerPluginLoadObserver gets
* notifications when plugins are loaded.
*
* @lib ProfilerEngine.exe/.lib???????????
* @since Series60_30.1
*/
class MSamplerPluginLoadObserver
{
public: // Enums
enum KSamplerPluginLoaderStatus
{
// One plugin loaded successfully, continue to next.
ESamplerSuccess,
// Loading one plugin failed, contiue to next.
ESamplerFail,
// Client called AbortAsyncLoad(), finished loading.
ESamplerAborted,
// All plugins loaded successfully, finished loading.
ESamplerFinished,
// Severe error with loader, finished loading.
ESamplerError
};
public: // New
//CSamplerPluginLoader calls this function when each plug-in is loaded or
//loading is finished..
IMPORT_C virtual void HandlePluginLoaded(
KSamplerPluginLoaderStatus aStatus ) = 0;
};
#endif // SAMPLERPLUGINLOADER_H
// End of File