hti/HtiFramework/inc/HtiDispatcher.h
changeset 0 a03f92240627
child 7 8a14024f954a
equal deleted inserted replaced
-1:000000000000 0:a03f92240627
       
     1 /*
       
     2 * Copyright (c) 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:  Implementation of MDispatcher interface that used
       
    15 *        to dispatch incoming messages to servers
       
    16 *        and outcoming to host client.
       
    17 *        MDispatcher should be used by services to send outcoming
       
    18 *        messages and by communication modules to dispatch messages.
       
    19 *        This is the main class in HtiFramework.
       
    20 *
       
    21 */
       
    22 
       
    23 
       
    24 #ifndef DISPATCHER_H__
       
    25 #define DISPATCHER_H__
       
    26 
       
    27 #include <e32base.h>
       
    28 #include <e32cons.h>
       
    29 #include "HtiDispatcherInterface.h"
       
    30 #include "HtiMessage.h"
       
    31 #include "HtiLogging.h"
       
    32 
       
    33 const static TUid KHtiSystemServiceUid = { 0x1020DEB6 };
       
    34 
       
    35 const static TInt KServiceArrayGranularity = 4;
       
    36 
       
    37 const static TInt KHandbrakeTimerIntervalMS = 100 * 1000; //in microseconds
       
    38 const static TInt KMaxFailedDispatchCalls = 4;
       
    39 
       
    40 //forward declarations
       
    41 class CHtiCommAdapter;
       
    42 //class CHtiMessage;
       
    43 class CHtiMessageQueue;
       
    44 class CHTIServicePluginInterface;
       
    45 class CHTICommPluginInterface;
       
    46 class CHtiSecurityManager;
       
    47 
       
    48 
       
    49 // HTI Framework error codes
       
    50 enum THtiError
       
    51     {
       
    52     EHtiErrBigMessage = 1,
       
    53     EHtiErrNoMemory,
       
    54     EHtiErrServiceNotFound,
       
    55     EHtiErrServiceError,
       
    56     EHtiErrNotAuthorized,
       
    57     EHtiErrUnwrap
       
    58     };
       
    59 
       
    60 // Types for restore factory settings
       
    61 enum TRfsType
       
    62     {
       
    63     ERfsUnknown = -1,
       
    64     ERfsNormal  = 0,
       
    65     ERfsDeep    = 1
       
    66     };
       
    67 
       
    68 /**
       
    69 * Helper class that constructs messages
       
    70 * used by the HTI system service
       
    71 *
       
    72 **/
       
    73 class THtiSystemProtocolHelper
       
    74     {
       
    75 public:
       
    76     static TDesC8* ErrorMessageL( TInt aHtiErrorCode,
       
    77                                   const TUid aTargetServiceUid );
       
    78     static TDesC8* ErrorMessageL( TInt aHtiErrorCode,
       
    79                                   const TUid aTargetServiceUid,
       
    80                                   TInt aErrorCode,
       
    81                                   const TDesC8& aErrorDescription );
       
    82     static TDesC8* AuthMessageL( const TDesC8& aToken );
       
    83     };
       
    84 
       
    85 class CHtiDispatcher:
       
    86     public CBase,
       
    87     public MHtiDispatcher
       
    88     {
       
    89 public:
       
    90     /**
       
    91     * Creates dispatcher. Leaves on failure.
       
    92     *
       
    93     * @param aCommPlugin plug-in name to use for communication
       
    94     * @param aMaxMsgSize maximum size for an incoming message
       
    95     * @param aMaxQueueMemorySize maximum size of all messages in the
       
    96     *        incoming queue
       
    97     * @param aShowConsole whether to open a console window for HTI
       
    98     * @param aShowErrorDialogs whether to show a dialog in case of critical
       
    99     *        error or just silently exit
       
   100     * @return pointer to the created CHtiDispatcher instance
       
   101     */
       
   102     static CHtiDispatcher* NewL( const TDesC8& aCommPlugin,
       
   103                                  TInt aMaxMsgSize,
       
   104                                  TInt aMaxQueueMemorySize,
       
   105                                  TBool aShowConsole,
       
   106                                  TBool aShowErrorDialogs );
       
   107 
       
   108     /**
       
   109     * Creates dispatcher and puts the created isntance to the cleanup stack.
       
   110     * Leaves on failure.
       
   111     *
       
   112     * @param aCommPlugin plug-in name to use for communication
       
   113     * @param aMaxMsgSize maximum size for an incoming message
       
   114     * @param aMaxQueueMemorySize maximum size of all messages in the
       
   115     *        incoming queue
       
   116     * @param aShowConsole whether to open a console window for HTI
       
   117     * @param aShowErrorDialogs whether to show a dialog in case of critical
       
   118     *        error or just silently exit
       
   119     * @return pointer to the created CHtiDispatcher instance
       
   120     */
       
   121     static CHtiDispatcher* NewLC( const TDesC8& aCommPlugin,
       
   122                                   TInt aMaxMsgSize,
       
   123                                   TInt aMaxQueueMemorySize,
       
   124                                   TBool aShowConsole,
       
   125                                   TBool aShowErrorDialogs );
       
   126 
       
   127     /**
       
   128     * Destructor. Frees the allocated resources.
       
   129     */
       
   130     ~CHtiDispatcher();
       
   131 
       
   132     /**
       
   133     *
       
   134     * Parse message to a corresponding service
       
   135     * The function returns immediately.
       
   136     * Transfer ownership of aMessage.
       
   137     *
       
   138     *  @param aMessage contains incoming message
       
   139     */
       
   140     void DispatchIncomingMessage( CHtiMessage* aMessage );
       
   141 
       
   142     /**
       
   143     * Construct and dispath HTI error message. For internal use.
       
   144     *
       
   145     * @param aHtiErrorCode error code
       
   146     * @param aTargetService UID of the service plug-in that caused the error
       
   147     * @return standard Symbian error code
       
   148     */
       
   149     TInt DispatchOutgoingErrorMessage( THtiError aHtiErrorCode,
       
   150                    const TUid aTargetService = KHtiSystemServiceUid );
       
   151 
       
   152 public: // Inherited methods from MHtiDispatcher
       
   153     TInt DispatchOutgoingMessage( TDesC8* aMessage,
       
   154                     const TUid aTargetServiceUid,
       
   155                     TBool aWrappedFlag,
       
   156                     THtiMessagePriority aPriority );
       
   157 
       
   158     TInt DispatchOutgoingMessage( TDesC8* aMessage,
       
   159                     const TUid aTargetServiceUid );
       
   160 
       
   161     TInt DispatchOutgoingErrorMessage( TInt aErrorCode,
       
   162                     const TDesC8& aErrorDescription,
       
   163                     const TUid aTargetServiceUid );
       
   164 
       
   165     /**
       
   166     * Adds memory observer.
       
   167     *
       
   168     * @param anObserver memory observer
       
   169     */
       
   170     void AddMemoryObserver( MHtiMemoryObserver* anObserver );
       
   171 
       
   172     /**
       
   173     * Removes memory observer.
       
   174     *
       
   175     * @param anObserver memory observer
       
   176     */
       
   177     void RemoveMemoryObserver( MHtiMemoryObserver* anObserver );
       
   178 
       
   179     /**
       
   180     * Returns the amount of memory available for message in the incoming queue
       
   181     *
       
   182     */
       
   183     TInt GetFreeMemory();
       
   184 
       
   185     void Notify( TInt aError );
       
   186 
       
   187     /*
       
   188     * Returns a pointer to the HTI console
       
   189     */
       
   190     CConsoleBase* GetConsole();
       
   191 
       
   192     /**
       
   193     * Unload all service plugins and clear queues
       
   194     */
       
   195     void Reset();
       
   196 
       
   197     /*
       
   198     * Shutdown HTI and reboot the device.
       
   199     *
       
   200     * Called from service plug-ins or from EHtiReboot HtiSystem command
       
   201     */
       
   202     void ShutdownAndRebootDeviceL();
       
   203 
       
   204     /*
       
   205     * Query the ShowErrorDialogs configuration value.
       
   206     * @return iShowErrorDialogs value
       
   207     */
       
   208     TBool GetShowErrorDialogs();
       
   209 
       
   210 protected:
       
   211     /**
       
   212     * Constructors
       
   213     *
       
   214     */
       
   215     CHtiDispatcher( TInt aMaxQueueMemorySize, TBool aShowErrorDialogs );
       
   216 
       
   217     void ConstructL( const TDesC8& aCommPlugin,
       
   218                      TInt aMaxMsgSize,
       
   219                      TBool aShowConsole );
       
   220 
       
   221     /**
       
   222     * Construct and dispath HTI error message. For internal use
       
   223     *
       
   224     * @param aHtiErrorCode error code
       
   225     * @param aLeaveCode leave code that caused error
       
   226     * @param aTargetServiceUid UID of the service plug-in that caused the error
       
   227     *
       
   228     */
       
   229     TInt DispatchOutgoingErrorMessage( THtiError aHtiErrorCode,
       
   230                                     TInt aLeaveCode,
       
   231                                     const TUid aTargetServiceUid );
       
   232 
       
   233     /**
       
   234     * Ensures that iIdle is started
       
   235     * when a new message come
       
   236     *
       
   237     */
       
   238     void Start();
       
   239 
       
   240     /**
       
   241     * Does message dispatching one at a time
       
   242     * This method is called by the static callback function
       
   243     * DispatchCallback().
       
   244     *
       
   245     */
       
   246     TInt DoDispatch();
       
   247 
       
   248     void DoMemoryNotification();
       
   249 
       
   250     /**
       
   251     * Callback functions called by CIdle in idel time to
       
   252     * process messages in the queues
       
   253     *
       
   254     * @param aObj the reference to a CHTIDispatcher is passed
       
   255     *             to call its non-static DoDispatch() method
       
   256     */
       
   257     static TInt DispatchCallback( TAny* aObj );
       
   258 
       
   259     /**
       
   260     * Finds and if needed loads specified service
       
   261     * Returns NULL if service in question was not found
       
   262     *
       
   263     */
       
   264     CHTIServicePluginInterface* GetService( const TUid aServiceUid );
       
   265 
       
   266     /**
       
   267     * Destructs all loaded services from iLoadedServices array.
       
   268     * Note this function does not delete iLoadedServices object itself.
       
   269     *
       
   270     */
       
   271     void UnloadAllServices();
       
   272 
       
   273     /**
       
   274     * Used instead of panic when framework cannot work further
       
   275     * Reason code and description used for logging
       
   276     *
       
   277     * @param aReason code for rebooting
       
   278     * @param aReasonDescr description
       
   279     */
       
   280     void UrgentReboot( TInt aReason, const TDesC8& aReasonDescr );
       
   281 
       
   282     /**
       
   283     * Handle HTI message addressed to HTI system service.
       
   284     * It's processed right in the dispatcher.
       
   285     * The method is trapped and no special actions if it leaves.
       
   286     * @param aMessage the message data
       
   287     */
       
   288     void HandleSystemMessageL( const TDesC8& aMessage );
       
   289 
       
   290     // functions to handle HTI system commands
       
   291 
       
   292     /**
       
   293     * Phone reboot
       
   294     *
       
   295     */
       
   296     void Reboot();
       
   297 
       
   298     /**
       
   299     * Activate restore factory settings. Causes also a reboot.
       
   300     * The mode of restore factory settings (normal or deep) is
       
   301     * defined by iRfsMode.
       
   302     */
       
   303     void RestoreFactorySettings();
       
   304 
       
   305     /**
       
   306     * Checks whether given file is in a ROM drive.
       
   307     * @param aFileName full path to the file to check
       
   308     */
       
   309     TBool IsFileInRom( const TDesC& aFileName );
       
   310 
       
   311     TDesC8* ServicePluginsListL();
       
   312 
       
   313     /**
       
   314     * Checks and readjust priorities of comm adapters and idle object to
       
   315     * prevent overflow of message queues.
       
   316     *
       
   317     */
       
   318     void CheckPriorities();
       
   319 
       
   320     /**
       
   321     * Kills HTI watchdog process if it exists.
       
   322     *
       
   323     */
       
   324     void KillHtiWatchDogL();
       
   325 
       
   326 #ifdef __ENABLE_LOGGING__
       
   327     /**
       
   328     * List in log files all found comm and service plugins
       
   329     */
       
   330     void DebugListPlugins();
       
   331 #endif
       
   332 
       
   333     /**
       
   334     * Generate unique ID for HTI instance.
       
   335     */
       
   336     void CreateInstanceId();
       
   337 
       
   338     /**
       
   339     * Maps the service plugin protocol UID to implementation UID and vice versa.
       
   340     */
       
   341     TUid MapServicePluginUid( const TUid aUid );
       
   342 
       
   343 private:
       
   344     /**
       
   345     * used to dispatch messages when thread is free
       
   346     */
       
   347     CIdle* iIdle;
       
   348 
       
   349     /**
       
   350     * Indicates that iIdle was started
       
   351     */
       
   352     TBool iIdleActive;
       
   353 
       
   354     /**
       
   355     * Incoming message queue
       
   356     * holds pointers to messages located in heap
       
   357     */
       
   358     CHtiMessageQueue* iIncomingQueue;
       
   359 
       
   360     /**
       
   361     * Outgoing message queue
       
   362     * holds pointers to messages located in heap
       
   363     */
       
   364     CHtiMessageQueue* iOutgoingQueue;
       
   365 
       
   366     /**
       
   367     * loaded service plugins description
       
   368     */
       
   369     struct TServiceItem
       
   370         {
       
   371         TUid iServiceUid;
       
   372         CHTIServicePluginInterface* iService; /** service instance */
       
   373         };
       
   374 
       
   375     /**
       
   376     * An array that keeps all loaded service plugins
       
   377     */
       
   378     RArray<TServiceItem>* iLoadedServices;
       
   379 
       
   380     /**
       
   381     * Memory observers
       
   382     */
       
   383     RPointerArray<MHtiMemoryObserver>* iMemoryObservers;
       
   384 
       
   385     /**
       
   386     * Instance of comm. plug-in used by iListener and iSender.
       
   387     * It's not used by dispatcher.
       
   388     */
       
   389     CHTICommPluginInterface* iCommPlugin;
       
   390 
       
   391     /**
       
   392     * CCommAdapter instance for constant receiving of incoming HTI messages
       
   393     */
       
   394     CHtiCommAdapter* iListener;
       
   395 
       
   396     /**
       
   397     * CCommAdapter instance for sending outgoing HTI messages
       
   398     */
       
   399     CHtiCommAdapter* iSender;
       
   400 
       
   401     /**
       
   402     * Security manager
       
   403     */
       
   404     CHtiSecurityManager* iSecurityManager;
       
   405 
       
   406     /**
       
   407     * maximum size of all messages in the incoming queue
       
   408     */
       
   409     const TInt iMaxQueueMemorySize;
       
   410 
       
   411     /**
       
   412     * Flag to indicate reboot after framework stoped
       
   413     */
       
   414     TBool iToReboot;
       
   415 
       
   416     /**
       
   417     * Flag indicating the requested factory settings restore mode.
       
   418     */
       
   419     TRfsType iRfsMode;
       
   420 
       
   421     /**
       
   422     * Queue size thresold for priorities readjusting
       
   423     */
       
   424     TInt iQueueSizeLowThresold;
       
   425     TInt iQueueSizeHighThresold;
       
   426 
       
   427     /**
       
   428     * Console for HTI
       
   429     */
       
   430     CConsoleBase* iConsole;
       
   431 
       
   432     /**
       
   433     * By default the idle object and comm adapters AO will have the same priority
       
   434     * iIdle will be added later to the AS that gives comm. adapter AO priority
       
   435     * In case of very fast incoming data there is possibility that idle will not be
       
   436     * called at all, because comm API will comlete async request at once. That will
       
   437     * lead to incoming queue overflow. The solution is to change AOs priorities.
       
   438     * Using AO priorities directly is complicated that active AO's priority cannot be changed.
       
   439     * So the order of AOs with equal priorities used to change the way they will be
       
   440     * picked up by AS.
       
   441     * When new incoming message is added, in comm adapter AO, the incoming queue is checked
       
   442     * in case it reaches predefined high-watermark, comm adapter AO is removed from AS and
       
   443     * added again, so idle AO will be picked next time.
       
   444     * when idle AO checks that incoming queue is less than predefined low-watermark, it will
       
   445     * remove itself and add to AS, to give a way to comm adapter's AO.
       
   446     * The following flag iIdleOverCommAdapter is used when idle is first in AS.
       
   447     *
       
   448     */
       
   449     TBool iIdleOverCommAdapter;
       
   450 
       
   451     /**
       
   452     * Unique ID for HTI instance.
       
   453     * The ID is generated only when it is queried for the first time (to add
       
   454     * randomness). Until then it's zero.
       
   455     */
       
   456     TUint32 iHtiInstanceId;
       
   457 
       
   458     /**
       
   459     * Indicates whether to show error dialogs (notifiers) in case of critical
       
   460     * errors or just silently exit.
       
   461     */
       
   462     TBool iShowErrorDialogs;
       
   463     };
       
   464 
       
   465 
       
   466 #endif