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 aReconnectDelay seconds of delay for reconnecting when connection

    98     *        lost. Value 0 means that reconnect would not happen.

    99     * @param aShowConsole whether to open a console window for HTI

   100     * @param aShowErrorDialogs whether to show a dialog in case of critical

   101     *        error or just silently exit

   102     * @return pointer to the created CHtiDispatcher instance

   103     */

   104     static CHtiDispatcher* NewL( const TDesC8& aCommPlugin,

   105                                  TInt aMaxMsgSize,

   106                                  TInt aMaxQueueMemorySize,

   107                                  TInt aReconnectDelay,

   108                                  TBool aShowConsole,

   109                                  TBool aShowErrorDialogs );

   110 

   111     /**

   112     * Creates dispatcher and puts the created isntance to the cleanup stack.

   113     * Leaves on failure.

   114     *

   115     * @param aCommPlugin plug-in name to use for communication

   116     * @param aMaxMsgSize maximum size for an incoming message

   117     * @param aMaxQueueMemorySize maximum size of all messages in the

   118     *        incoming queue

   119     * @param aReconnectDelay seconds of delay for reconnecting when connection

   120     *        lost. Value 0 means that reconnect would not happen.

   121     * @param aShowConsole whether to open a console window for HTI

   122     * @param aShowErrorDialogs whether to show a dialog in case of critical

   123     *        error or just silently exit

   124     * @return pointer to the created CHtiDispatcher instance

   125     */

   126     static CHtiDispatcher* NewLC( const TDesC8& aCommPlugin,

   127                                   TInt aMaxMsgSize,

   128                                   TInt aMaxQueueMemorySize,

   129                                   TInt aReconnectDelay,

   130                                   TBool aShowConsole,

   131                                   TBool aShowErrorDialogs );

   132 

   133     /**

   134     * Destructor. Frees the allocated resources.

   135     */

   136     ~CHtiDispatcher();

   137 

   138     /**

   139     *

   140     * Parse message to a corresponding service

   141     * The function returns immediately.

   142     * Transfer ownership of aMessage.

   143     *

   144     *  @param aMessage contains incoming message

   145     */

   146     void DispatchIncomingMessage( CHtiMessage* aMessage );

   147 

   148     /**

   149     * Construct and dispath HTI error message. For internal use.

   150     *

   151     * @param aHtiErrorCode error code

   152     * @param aTargetService UID of the service plug-in that caused the error

   153     * @return standard Symbian error code

   154     */

   155     TInt DispatchOutgoingErrorMessage( THtiError aHtiErrorCode,

   156                    const TUid aTargetService = KHtiSystemServiceUid );

   157 

   158 public: // Inherited methods from MHtiDispatcher

   159     TInt DispatchOutgoingMessage( TDesC8* aMessage,

   160                     const TUid aTargetServiceUid,

   161                     TBool aWrappedFlag,

   162                     THtiMessagePriority aPriority );

   163 

   164     TInt DispatchOutgoingMessage( TDesC8* aMessage,

   165                     const TUid aTargetServiceUid );

   166 

   167     TInt DispatchOutgoingErrorMessage( TInt aErrorCode,

   168                     const TDesC8& aErrorDescription,

   169                     const TUid aTargetServiceUid );

   170 

   171     /**

   172     * Adds memory observer.

   173     *

   174     * @param anObserver memory observer

   175     */

   176     void AddMemoryObserver( MHtiMemoryObserver* anObserver );

   177 

   178     /**

   179     * Removes memory observer.

   180     *

   181     * @param anObserver memory observer

   182     */

   183     void RemoveMemoryObserver( MHtiMemoryObserver* anObserver );

   184 

   185     /**

   186     * Returns the amount of memory available for message in the incoming queue

   187     *

   188     */

   189     TInt GetFreeMemory();

   190 

   191     void Notify( TInt aError );

   192 

   193     /*

   194     * Returns a pointer to the HTI console

   195     */

   196     CConsoleBase* GetConsole();

   197 

   198     /**

   199     * Unload all service plugins and clear queues

   200     */

   201     void Reset();

   202 

   203     /*

   204     * Shutdown HTI and reboot the device.

   205     *

   206     * Called from service plug-ins or from EHtiReboot HtiSystem command

   207     */

   208     void ShutdownAndRebootDeviceL();

   209 

   210     /*

   211     * Query the ShowErrorDialogs configuration value.

   212     * @return iShowErrorDialogs value

   213     */

   214     TBool GetShowErrorDialogs();

   215 

   216     

   217     /*

   218      * Delay a period and reconnect when connection lost.

   219      * If the period is 0, reconnect would not happen.

   220      * @return whether reconnect

   221      */

   222      TBool CommReconnect();

   223      

   224 protected:

   225     /**

   226     * Constructors

   227     *

   228     */

   229     CHtiDispatcher( TInt aMaxQueueMemorySize, TInt aReconnectDelay, TBool aShowErrorDialogs );

   230 

   231     void ConstructL( const TDesC8& aCommPlugin,

   232                      TInt aMaxMsgSize,

   233                      TBool aShowConsole );

   234 

   235     /**

   236     * Construct and dispath HTI error message. For internal use

   237     *

   238     * @param aHtiErrorCode error code

   239     * @param aLeaveCode leave code that caused error

   240     * @param aTargetServiceUid UID of the service plug-in that caused the error

   241     *

   242     */

   243     TInt DispatchOutgoingErrorMessage( THtiError aHtiErrorCode,

   244                                     TInt aLeaveCode,

   245                                     const TUid aTargetServiceUid );

   246 

   247     /**

   248     * Ensures that iIdle is started

   249     * when a new message come

   250     *

   251     */

   252     void Start();

   253 

   254     /**

   255     * Does message dispatching one at a time

   256     * This method is called by the static callback function

   257     * DispatchCallback().

   258     *

   259     */

   260     TInt DoDispatch();

   261 

   262     void DoMemoryNotification();

   263 

   264     /**

   265     * Callback functions called by CIdle in idel time to

   266     * process messages in the queues

   267     *

   268     * @param aObj the reference to a CHTIDispatcher is passed

   269     *             to call its non-static DoDispatch() method

   270     */

   271     static TInt DispatchCallback( TAny* aObj );

   272 

   273     /**

   274     * Finds and if needed loads specified service

   275     * Returns NULL if service in question was not found

   276     *

   277     */

   278     CHTIServicePluginInterface* GetService( const TUid aServiceUid );

   279 

   280     /**

   281     * Destructs all loaded services from iLoadedServices array.

   282     * Note this function does not delete iLoadedServices object itself.

   283     *

   284     */

   285     void UnloadAllServices();

   286 

   287     /**

   288     * Used instead of panic when framework cannot work further

   289     * Reason code and description used for logging

   290     *

   291     * @param aReason code for rebooting

   292     * @param aReasonDescr description

   293     */

   294     void UrgentReboot( TInt aReason, const TDesC8& aReasonDescr );

   295 

   296     /**

   297     * Handle HTI message addressed to HTI system service.

   298     * It's processed right in the dispatcher.

   299     * The method is trapped and no special actions if it leaves.

   300     * @param aMessage the message data

   301     */

   302     void HandleSystemMessageL( const TDesC8& aMessage );

   303 

   304     // functions to handle HTI system commands

   305 

   306     /**

   307     * Phone reboot

   308     *

   309     */

   310     void Reboot();

   311 

   312     /**

   313     * Activate restore factory settings. Causes also a reboot.

   314     * The mode of restore factory settings (normal or deep) is

   315     * defined by iRfsMode.

   316     */

   317     void RestoreFactorySettings();

   318 

   319     /**

   320     * Checks whether given file is in a ROM drive.

   321     * @param aFileName full path to the file to check

   322     */

   323     TBool IsFileInRom( const TDesC& aFileName );

   324 

   325     TDesC8* ServicePluginsListL();

   326 

   327     /**

   328     * Checks and readjust priorities of comm adapters and idle object to

   329     * prevent overflow of message queues.

   330     *

   331     */

   332     void CheckPriorities();

   333 

   334     /**

   335     * Kills HTI watchdog process if it exists.

   336     *

   337     */

   338     void KillHtiWatchDogL();

   339 

   340 #ifdef __ENABLE_LOGGING__

   341     /**

   342     * List in log files all found comm and service plugins

   343     */

   344     void DebugListPlugins();

   345 #endif

   346 

   347     /**

   348     * Generate unique ID for HTI instance.

   349     */

   350     void CreateInstanceId();

   351 

   352     /**

   353     * Maps the service plugin protocol UID to implementation UID and vice versa.

   354     */

   355     TUid MapServicePluginUid( const TUid aUid );

   356 

   357 private:

   358     /**

   359     * used to dispatch messages when thread is free

   360     */

   361     CIdle* iIdle;

   362 

   363     /**

   364     * Indicates that iIdle was started

   365     */

   366     TBool iIdleActive;

   367 

   368     /**

   369     * Incoming message queue

   370     * holds pointers to messages located in heap

   371     */

   372     CHtiMessageQueue* iIncomingQueue;

   373 

   374     /**

   375     * Outgoing message queue

   376     * holds pointers to messages located in heap

   377     */

   378     CHtiMessageQueue* iOutgoingQueue;

   379 

   380     /**

   381     * loaded service plugins description

   382     */

   383     struct TServiceItem

   384         {

   385         TUid iServiceUid;

   386         CHTIServicePluginInterface* iService; /** service instance */

   387         };

   388 

   389     /**

   390     * An array that keeps all loaded service plugins

   391     */

   392     RArray<TServiceItem>* iLoadedServices;

   393 

   394     /**

   395     * Memory observers

   396     */

   397     RPointerArray<MHtiMemoryObserver>* iMemoryObservers;

   398 

   399     /**

   400     * Instance of comm. plug-in used by iListener and iSender.

   401     * It's not used by dispatcher.

   402     */

   403     CHTICommPluginInterface* iCommPlugin;

   404 

   405     /**

   406     * CCommAdapter instance for constant receiving of incoming HTI messages

   407     */

   408     CHtiCommAdapter* iListener;

   409 

   410     /**

   411     * CCommAdapter instance for sending outgoing HTI messages

   412     */

   413     CHtiCommAdapter* iSender;

   414 

   415     /**

   416     * Security manager

   417     */

   418     CHtiSecurityManager* iSecurityManager;

   419 

   420     /**

   421     * maximum size of all messages in the incoming queue

   422     */

   423     const TInt iMaxQueueMemorySize;

   424 

   425     /**

   426     * Flag to indicate reboot after framework stoped

   427     */

   428     TBool iToReboot;

   429 

   430     /**

   431     * Flag indicating the requested factory settings restore mode.

   432     */

   433     TRfsType iRfsMode;

   434 

   435     /**

   436     * Queue size thresold for priorities readjusting

   437     */

   438     TInt iQueueSizeLowThresold;

   439     TInt iQueueSizeHighThresold;

   440 

   441     /**

   442     * Console for HTI

   443     */

   444     CConsoleBase* iConsole;

   445 

   446     /**

   447     * By default the idle object and comm adapters AO will have the same priority

   448     * iIdle will be added later to the AS that gives comm. adapter AO priority

   449     * In case of very fast incoming data there is possibility that idle will not be

   450     * called at all, because comm API will comlete async request at once. That will

   451     * lead to incoming queue overflow. The solution is to change AOs priorities.

   452     * Using AO priorities directly is complicated that active AO's priority cannot be changed.

   453     * So the order of AOs with equal priorities used to change the way they will be

   454     * picked up by AS.

   455     * When new incoming message is added, in comm adapter AO, the incoming queue is checked

   456     * in case it reaches predefined high-watermark, comm adapter AO is removed from AS and

   457     * added again, so idle AO will be picked next time.

   458     * when idle AO checks that incoming queue is less than predefined low-watermark, it will

   459     * remove itself and add to AS, to give a way to comm adapter's AO.

   460     * The following flag iIdleOverCommAdapter is used when idle is first in AS.

   461     *

   462     */

   463     TBool iIdleOverCommAdapter;

   464 

   465     /**

   466     * Unique ID for HTI instance.

   467     * The ID is generated only when it is queried for the first time (to add

   468     * randomness). Until then it's zero.

   469     */

   470     TUint32 iHtiInstanceId;

   471 

   472     /**

   473     * Indicates whether to show error dialogs (notifiers) in case of critical

   474     * errors or just silently exit.

   475     */

   476     TBool iShowErrorDialogs;

   477     

   478     /**

   479      * Delay a period and reconnect when connection lost.

   480      * If the period is 0, reconnect would not happen.

   481      */

   482     TInt iReconnectDelay;

   483     

   484     /**

   485      * Indicates reboot reason.

   486      * Reason type is defined in enum RStarterSession::TResetReason value in starterclient.h

   487      */

   488     TInt iRebootReason;

   489     };

   490 

   491 

   492 #endif