1 /*

     2 * Copyright (c) 2005-2006 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:  CMnAiwCommandHandlerBase class declaration

    15 *

    16 */

    17 

    18 

    19 #ifndef MN_AIWCOMMANDHANDLERBASE_H

    20 #define MN_AIWCOMMANDHANDLERBASE_H

    21 

    22 #include <e32base.h>

    23 #include <AiwCommon.h>

    24 #include <AknServerApp.h>

    25 #include <EPos_Landmarks.h>

    26 #include "mnprovider.h"

    27 #include "mnaiwservices.h"

    28 

    29 class CMnAiwCommandHandlerBase;

    30 class CPosLandmark;

    31 

    32 /** \internal 

    33  *  Callback for clients of @ref CMnAiwCommandHandlerBase.

    34  *  Used by CMnAiwProvider to destroy asynchronous handlers.

    35  */

    36 class MMnAsyncAiwCmdHandlerCallback

    37     {

    38     public:

    39         /** Called by CMnAiwCommandHandlerBase-derived class, 

    40          *  to notify completion of AIW command async handling.

    41          *  @param aHandler pointer to completed command's handler

    42          *  @param aResult result of the command execution

    43          */

    44         virtual void HandleAsyncAiwCmdCompletedL( 

    45             CMnAiwCommandHandlerBase* aHandler, 

    46             TInt aResult ) = 0;

    47     };

    48 

    49 /** \internal 

    50  *  Callback for clients of @ref CMnAiwCommandHandlerBase.

    51  *  Used by CMnAiwProvider to destroy handlers, when provider is shutdown.

    52  */

    53 class MMnProviderExitCallback

    54     {

    55     public:

    56         /** Called by CMnAiwCommandHandlerBase-derived class, 

    57          *  to notify provider's exit.

    58          *  @param aHandler pointer to completed command's handler

    59          */

    60         virtual void HandleProviderExit( 

    61             CMnAiwCommandHandlerBase* aHandler ) = 0;

    62     };

    63 

    64 /** \internal 

    65  *  Base class for AIW command handlers 

    66  */

    67 class CMnAiwCommandHandlerBase : public CActive, public MAknServerAppExitObserver

    68     {

    69     public:

    70         /** Holder for AIW parameters */

    71         class TAiwParameters

    72             {

    73             public:

    74                 TAiwParameters();

    75                 TAiwParameters(

    76                     const CAiwGenericParamList& aInParamList,

    77                     CAiwGenericParamList& aOutParamList,

    78                     const MAiwNotifyCallback* aCallback

    79                     );

    80                 

    81                 const CAiwGenericParamList&     InList() const;

    82                 CAiwGenericParamList&           OutList();

    83                 const MAiwNotifyCallback*       Callback() const;

    84                 

    85             protected:        

    86                 const CAiwGenericParamList*     iInParamList;

    87                 CAiwGenericParamList*           iOutParamList;

    88                 const MAiwNotifyCallback*       iCallback;

    89             };

    90     

    91         enum TRunMode

    92             {

    93             ERunModeDefault,

    94             ERunModeChained,

    95             ERunModeStandalone

    96             };

    97     

    98     public:

    99         /** Returns information about what Provider Application's 

   100          *  facilities are needed to execute a particular command

   101          */

   102         static void AppServiceAndFeatureNeeded(

   103             TInt aAiwServiceCommand, 

   104             CMnProvider::TService& aServiceNeeded,

   105             TInt& aFeaturesNeeded );

   106             

   107         /** Returns default execution mode for a command.

   108          *  @param aAiwServiceCommand Command ID */    

   109         static TRunMode DefaultRunMode( TInt aAiwServiceCommand );

   110 

   111         /** Creates new command handler.

   112          *  @param aAiwServiceCommand Command ID

   113          *  @param[in] aAiwParams Initial AIW parameters. Needed to detect requested

   114          *                        execution mode.

   115          *  @return New instance of command handler

   116          *  @leave KErrNotSupported If given command is not supported

   117          */

   118         static CMnAiwCommandHandlerBase* CreateHandlerL( 

   119             TInt aAiwServiceCommand, 

   120             CMnProvider& aProvider,

   121             TRunMode aRunMode );

   122 

   123         /** Analyzes TMnAiwCommonOptionsParam ( if present ) to see 

   124          *  whether chained execution is needed.

   125          *  @param aDefaultMode default value to return if parameter is not found in the list.

   126          *  @return Execution mode requested in AIW parameters as defined in

   127          *          TMnAiwCommonOptionsParam::iRunChained is ETrue.

   128          */

   129         static TRunMode RequestedRunModeL( const TAiwParameters& aAiwParams );

   130 

   131         /** Analyzes TMnAiwCommonOptionsParamExtended ( if present ) to see 

   132          *  whether provider application is specified.

   133          *  @param[out] aProviderId provider application UID, if specified.

   134          *  @return ETrue if provider application UID is specified, otherwise EFalse.

   135          */

   136         static TBool IsProviderSpecifiedL( 

   137             const CMnAiwCommandHandlerBase::TAiwParameters& aAiwParams,

   138             TInt& aProviderId );

   139 

   140         /** Analyzes TMnAiwCommonOptionsParamExtended ( if present ) to see 

   141          *  whether error messages are disabled.

   142          *  @return ETrue if error messages are disables, otherwise EFalse.

   143          */

   144         static TBool IsErrorMessageDisabledL( 

   145             const CMnAiwCommandHandlerBase::TAiwParameters& aAiwParams );

   146 

   147     public:

   148 

   149         /** Destructor */

   150         virtual ~CMnAiwCommandHandlerBase();

   151 

   152         /** Executes this command synchronously.

   153          *  If provider exits, it is reported via MMnProviderExitCallback */

   154         void StartL();

   155 

   156         /** Starts asynchronous processing of this command. 

   157          *  Completion of a command is reported via MMnAsyncAiwCmdHandlerCallback 

   158          *  @param[in] aCallback Object to notify, when request is completed */

   159         void Start( MMnAsyncAiwCmdHandlerCallback& aCallback );

   160         

   161         /** AIW service command id implemented by the handler */

   162         virtual TInt CommandId() = 0;

   163 

   164         /** Returns whether this command is asynchronous

   165          *  Async commands must be started by StartL, sync commands - by ExecuteL */

   166         virtual TBool IsAsyncCommand() = 0;

   167 

   168         /** Returns AIW command parameters */

   169         TAiwParameters& AiwParameters();

   170         

   171         /** Returns execution mode of the command */

   172         TRunMode RunMode();

   173         

   174         /** Sets parameters for this command. */

   175         void SetParametersL( const TAiwParameters& aParams );

   176         

   177         /** Called by before setting new parameters. Not called for the first time

   178          *  this command is executed. */

   179         virtual void ResetParametersL() = 0;

   180         

   181         virtual void SetExitObserverL( MMnProviderExitCallback& aExitCallback );

   182 

   183         /** Returns reference to provider used by this command handler */

   184         CMnProvider& Provider();

   185 

   186     protected:

   187         /** C++ constructor 

   188          *  @param aProvider Provider Application to use

   189          *  @param aAiwParameters Parameters sent to AIW Provider class

   190          *  @param aCallback Observer of this command's completion if command

   191          *                   is asynchronously executed

   192          */

   193         CMnAiwCommandHandlerBase( CMnProvider& aProvider );

   194     

   195         /** Symbian constructor. Must be called by derived classes */

   196         void ConstructL();

   197         

   198         /** Reports completion of the command, when executed asynchronously

   199          *  It should be safe to delete this object after this method is called.

   200          *  Used by derived classes */

   201         void Done( TInt aResult );

   202 

   203         /** Starts processing of input AIW parameters. Parameters found are reported

   204          *  via HandleAiwParam... handlers.

   205          */

   206         void ProcessAiwParametersL();

   207 

   208         /** Finds common options parameter in given parameter list */

   209         static TBool FindCommonOptionsL( 

   210             const TAiwParameters& aAiwParams, 

   211             TMnAiwCommonOptionsParamExtended& aCommonOptions );

   212 

   213         /** Finds i-th landmark data in input parameter list */

   214         TBool FindLandmarkData( TInt aIndex, TAiwGenericParam& aParam );

   215 

   216         /** Reads landmark data from given AIW parameter */

   217         void ReadLandmarkDataL( const TAiwGenericParam& aParam, TPtrC8& aLandmarkPtr );

   218 

   219         /** Reads landmark database URI from given AIW parameter */

   220         void ReadDatabaseUriL( const TAiwGenericParam& aParam, TPtrC& aDbUri );

   221 

   222         /** Reads landmark ID from given AIW parameter */

   223         TPosLmItemId ReadLandmarkId( const TAiwGenericParam& aParam );

   224 

   225         /** Reads landmark ID list from given AIW parameter */

   226         void ReadLandmarkIdListL( 

   227             const TAiwGenericParam& aParam,

   228             const TPosLmItemId*& aListPtr,

   229             TInt& aListSize );

   230 

   231         /** Appends given landmark to AIW output parameters list */

   232         void WriteLandmarkL( const CPosLandmark& aLandmark );

   233         

   234         /** Appends given landmark to AIW output parameters list */

   235         void WriteLandmarkL( TPosLmItemId aLandmarkId, const TDesC& aDatabaseUri );

   236         

   237     protected: // Virtual callbacks for parameter list parsing

   238     

   239         /** Called when ProcessAiwParametersL finds unknown AIW parameter */

   240         virtual void HandleAiwParamL( const TAiwGenericParam& aParam );        

   241         /** Called by ProcessAiwParametersL to report found landmarks */

   242         virtual void HandleAiwParamLandmarksL( RArray<TPtrC8>& aLandmarkDataList );

   243         /** Called by ProcessAiwParametersL to report found linked landmarks */

   244         virtual void HandleAiwParamLandmarksListL( const TDesC& aDbUri, RArray<TPosLmItemId>& aLmIds );

   245         

   246     public: // from CActive

   247         virtual void RunL();

   248         virtual TInt RunError( TInt aError );

   249         virtual void DoCancel();

   250 

   251 	protected: // from MAknServerAppExitObserver

   252         virtual void HandleServerAppExit( TInt aReason );

   253         virtual void DoStartL() = 0;

   254 

   255 	protected:

   256         TRunMode    						iRunMode;

   257 

   258     private:

   259         CMnProvider&                    	iProvider;

   260         TAiwParameters                  	iAiwParameters;

   261         MMnAsyncAiwCmdHandlerCallback*   	iCallback;

   262         MMnProviderExitCallback* 	        iExitCallback;

   263     };

   264 

   265 #endif // MN_AIWCOMMANDHANDLERBASE_H