1 /*

     2 * Copyright (c) 2008 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:  

    15 *

    16 *  ChspsClient is a client-side implementation of MhspsInstallationService and MhspsMaintenanceService

    17 *  interface definitions of Homescreen Plugin Configuration Managament Services APIs. Installation and 

    18 *  Maintenance Services are intended to serve Homescreen as well as S60 legacy applications - especially

    19 *  the Personalisation Application - with the plugin installation and maintenance 

    20 *  functionality. Typical use-case is that client application initiates ChspsClient-object, connects

    21 *  to hspsThemeServer with its application UID, and commences installation and maintenance service 

    22 *  requests.

    23 *

    24 *  Security in using services is quarantied by controlling the rights to see Application Themes 

    25 *  and operate with hsps Theme Server. This control is based on SECUREID of application process.

    26 *  Security is maintained behind the curtain by means of Symbian EKA2 Kernel services for Platform

    27 *  Security.

    28 *

    29 *  ChspsClient offers high- and low-level API-functionality. High-level and low-level calls are 

    30 *  diffrentiated by their parametrization. High-level parametrization is directed to the be used by

    31 *  applications which need human readable data and offer a user interface. Low-level parametrization

    32 *  is directed to the machine-originated requestors like OTA Push or DM (Device Management) 

    33 *  sub-systems where data is not needed to understand semanticly. 

    34 *  ChspsClient delegates server messages to its client application by 

    35 *  MhspsThemeManagementServiceObserver::HandlehspsClientMessage() call-back to be implemented by the 

    36 *  client application.

    37 *

    38 *  Theme Installation Services

    39 *  ===========================

    40 *  Processing a installation task works in asynchronous mode, however, synchronous mode is applied 

    41 *  everytime the installation is initiated. After checking installation rights and files validities,

    42 *  hsps Theme Server will allow actual installation. Client application must call actual  

    43 *  installation by commencing next phase execution explicitly. First call of installation returns 

    44 *  the ODT-header of the theme to be installed. This is to enable previewing information about 

    45 *  a theme to be installed. In this point, user can accept or decline the installation. 

    46 *  Installation preview feature is useful especially in OTA-service cases when user acception on 

    47 *  theme installation might be selected a a part of user policy settings.

    48 *  A theme can include resources that can be imported to the target system as such like some audio

    49 *  files etc., however, most of the images must be fitted on to the target device's color depth and

    50 *  pixel density. In these cases, the needed conversions will be executed asynchronously on 

    51 *  server-side. Asynchronous installation is executed in phases - resource by resource. 

    52 *  Installation phases are promoted automaticly, however, client application can control and 

    53 *  monitor installation phases, and also cancel installation at any time. If installation is 

    54 *  cancelled, hspsThemeServer initiates roll-back functionality removing inconsistent installation.  

    55 *

    56 *  Theme Maintenanace Services:

    57 *  ============================

    58 *  Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().

    59 *  Others functions are straightforward to use. They are explained in the class declaration section

    60 *  below. The asynchronous service is applied only in theme listing service calls.

    61 *  Client application initiates the theme listing by calling synchronous function 

    62 *  hspsGetListHeaders(). This call initiates the query. Client application should call 

    63 *  hspsGetNextHeader() after checking that any themes matching on current query is found or that query

    64 *  is valid at least. This action is called a subscription. To receive actual theme listing, the 

    65 *  client application must start to listen call-back messages from the server about list delivery. 

    66 *  The headers matching on query will be delivered immediately. Query remains until 

    67 *  hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, 

    68 *  it will be delivered if the query concers it. 

    69 *

    70 *

    71 *

    72 */

    73 

    74 

    75 #ifndef __ChspsCLIENT_H__

    76 #define __ChspsCLIENT_H__

    77 

    78 #include <e32base.h>

    79 

    80 #include "hspsthememanagement.h"

    81 #include "hspsclientsession.h"

    82 #include "hspsresult.h"

    83 

    84 #ifdef HSPS_LOG_ACTIVE

    85 class ChspsLogBus;

    86 #endif

    87 

    88 /** hspsClient Panic Category. */

    89 _LIT( KhspsClient, "hspsClient" );

    90 

    91 /** hspsClient panic codes: */

    92 enum ThspsClientPanics

    93     {

    94     EhspsClientBadState

    95     };

    96 

    97 class RhspsClientSession;

    98 class MhspsInstallationService;

    99 class MhspsMaintenanceService;

   100 class MhspsThemeManagementServiceObserver;

   101 class ChspsODT;

   102 class ChspsResult;

   103 

   104 /**

   105  *  ChspsClient. 

   106  *  ChspsClient performs all client-side theme installation and maintenance related functionality.

   107  *  Theme maintenance services includes theme listings, theme activation, theme removal, and default

   108  *  theme restoring functionality.

   109  *

   110  *  Class inheritance:

   111  *  ==================

   112  *  ChspsClient derives CActive for asynchronous request handling, and MhspsInstallationService and 

   113  *  MhspsMaintenanceService from Homescreenpluginservices. 

   114  *

   115  *  Theme installation functionality:

   116  *  =================================

   117  *  Client application must call hspsInstallNextPhaseL() after testing that the synchronous call 

   118  *  hspsInstallTheme() has returned EhspsInstallPhaseSuccess return code signalling that actual 

   119  *  installation is allowed. The rest of the installation phases will be executed automatically,

   120  *  however, installation can be interrupted by calling hspsCancelInstallTheme() at any time. 

   121  *  If installation is canceled, hspsThemeServer initiates roll-back functionality removing

   122  *  inconsistent installation.

   123  *  Installation service uses specific manifest-file format to get informed about the xml, css, 

   124  *  dtd, and resource files to be installed. Resource files might be locale-specific or generic

   125  *  as well.

   126  *  hspsThemeServer takes care of saving everything on their appropriate places in the target device's

   127  *  user disk. Theme storage is located in hspsThemeServer's private-folder.

   128  *  Locales are instructed in manifest file also. Manifest file's file-extension must be .dat, 

   129  *  but actually, the file-name can be whatever, however, when low-level parametrization is used, 

   130  *  the name must be "manifest.dat" and it must be the last file extracted from the installation 

   131  *  package.

   132  *  For more information of manifest-file format, see Homescreen wikipages.

   133  *

   134  *  Installation functions can return one of the following ThspsServiceCompletedMessage-codes:

   135  *  - EhspsInstallThemeSuccess,

   136  *  - EhspsInstallPhaseSuccess, or

   137  *  - EhspsInstallThemeFailed.

   138  *

   139  *  Client application must implement MhspsThemeManagementServiceObserver-interface and listen these 

   140  *  messages mentioned. Let it be emphasised that both synchronous and asynchronous calls can return

   141  *  the codes above. Installation functions may also return one of the following codes:

   142  *  - EhspsServiceRequestSheduled, or

   143  *  - EhspsServiceRequestError.

   144  *

   145  *  For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.

   146  *

   147  *  Theme maintenance functionality:

   148  *  ================================

   149  *  Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().

   150  *  Others functions are straightforward to use but hspsGetListHeaders(). This will be explained next; 

   151  *  synchronous call hspsGetListHeaders() initiates the theme header listing by passing search mask 

   152  *  to HSPS Server's Maintenance Service. This search mask is called a query. It also passes

   153  *  a list object in where maintenance service should append theme-header objects (type of 

   154  *  ChspsODT-class without DOM-document) when one is retrieved asychronously. Search mask should be 

   155  *  filled with proper parameters matching the need in hand. If no parameters are given, all headers

   156  *  of Application Themes available in Definition Repository will be delivered, otherwise, 

   157  *  only sub-set of theme-headers will be delivered. After the query-call hspsGetListHeaders(), the 

   158  *  delivering of the theme-headers is asynchronous. Asynchronous service must be initiated by 

   159  *  calling hspsGetNextHeader() after checking that any theme matching on current query is found or

   160  *  that query is valid anyway. This action is called a subscription. To receive theme

   161  *  listing, the client application must implement MhspsThemeManagementServiceObserver-interface and

   162  *  start to listen call-back messages. 

   163  *  The headers matching on query will be delivered immediately. Query remains until 

   164  *  hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, it

   165  *  will be delivered. As mentioned, when hspsGetListHeaders() returns, the return value must be checked.

   166  *  Return value could be one of the following:

   167  *  - EhspsGetListHeadersSuccess - there is at least one Application Theme available matching on query. 

   168  *                               Call first hspsGetNextHeader() to get the headers. Same call will set 

   169  *                               the subscribtion of new ones possible coming available later.

   170  *  - EhspsGetListHeadersEmpty   - there is no themes matching on the query available at the time, 

   171  *                               however, some might be exist later in due to installations. 

   172  *                               Client application should retain the subcription.

   173  *  - EhspsGetListHeadersFailed  - service request failed for some reason. Possible reasons are for e.g.

   174  *                               the missing rights to list headers queried.  

   175  *   

   176  *  Additional Return Code Support (ChspsResult) will express for e.g. the number of headers to be

   177  *  delivered or possible system error code in failed cases.

   178  *  

   179  *  By MhspsServiceObserver::HandlehspsServiceMessage() call-back function implementation, client 

   180  *  application must listen the following ThspsServiceCompletedMessage-messages:

   181  *

   182  *  - EhspsGetListHeadersUpdate  - header list on the client side has a new object appended at the end

   183  *                               of the list,

   184  *  - EhspsGetListHeadersRestart - header list on server side has changed so much that the client must 

   185  *                               empty the list printed on screen. New list will be delivered 

   186  *                               immediately. The subscription stands.

   187  *  - EhspsGetListHeadersEmpty   - header list on server side is now empty. The client must empty 

   188  *                               the list on screen if printed. The subscription stands. 

   189  *  - EhspsGetListHeadersFailed  - operation has failed. Client should cancel request and restart.

   190  *

   191  *  Maintenanace functions may also return one of the following codes:

   192  *  - EhspsServiceRequestSheduled, or

   193  *  - EhspsServiceRequestError.

   194  *

   195  *  For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.

   196  *

   197  *

   198  * @lib hspsClient.lib

   199  * @since S60 5.0

   200  * @ingroup group_hspsclients

   201  */

   202 class ChspsClient : public CActive, public MhspsInstallationService, public MhspsMaintenanceService

   203     {

   204     public: // Constructors and destructors

   205         /**

   206         * NewL.

   207         * 

   208         * Two-phased constructor.

   209         * Creates a ChspsClient object using two phase construction,

   210         * and return a pointer to the created object.

   211         * 

   212         * @since S60 5.0 

   213         * @param aObserver The object to be used to handle updates from the server.

   214         */

   215         IMPORT_C static ChspsClient* NewL(MhspsThemeManagementServiceObserver& aObserver );

   216 

   217         /**

   218         * NewLC.

   219         * 

   220         * Two-phased constructor.

   221         * Creates a ChspsClinet object using two phase construction,

   222         * and return a pointer to the created object.

   223         * 

   224         * @since S60 5.0

   225         * @param aObserver The object to be used to handle updates from the server.

   226         */

   227         IMPORT_C static ChspsClient* NewLC( MhspsThemeManagementServiceObserver& aObserver );

   228 

   229         /**

   230         * ~ChspsClient.

   231         * 

   232         * Destructor.

   233         * Destroys the object and release all memory objects.

   234         */

   235         virtual ~ChspsClient();

   236 

   237     public: // New functions

   238 

   239         /**

   240         * From MhspsInstallationService.

   241         */

   242 

   243         IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName,

   244                                    ChspsODT& aHeader);

   245 

   246         /**

   247         * From MhspsInstallationService.

   248         */

   249         IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName, 

   250                                    TDes8& aHeaderData);

   251 

   252         /**

   253         * From MhspsInstallationService.

   254         */

   255         IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(ChspsODT& aHeader);

   256 

   257         /**

   258         * From MhspsInstallationService.

   259         */

   260         IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(TDes8& aHeaderData);

   261 

   262         /**

   263         * From MhspsInstallationService.

   264         */

   265         IMPORT_C ThspsServiceCompletedMessage hspsCancelInstallTheme();

   266 

   267         /**

   268         * From MhspsMaintenanceService.

   269         */

   270         IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const ChspsODT& aSearchMask,

   271                                    CArrayPtrFlat<ChspsODT>& aHeaderList);

   272         

   273         /** 

   274         * From MhspsMaintenanceService.

   275         */

   276         IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const TDesC8& aSearchMaskData,

   277                                    CArrayPtrSeg<HBufC8>& aHeaderDataList);

   278         

   279         /**

   280         * From MhspsMaintenanceService.

   281         */  

   282         IMPORT_C ThspsServiceCompletedMessage hspsGetNextHeader();       

   283         

   284         /**

   285         * From MhspsMaintenanceService.

   286         */  

   287         IMPORT_C ThspsServiceCompletedMessage hspsCancelGetListHeaders();       

   288         

   289         /**

   290         * From MhspsMaintenanceService.

   291         */

   292         IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const ChspsODT& aSetMask,

   293                                    ChspsODT& aHeader);

   294        

   295         /**

   296         * From MhspsMaintenanceService.

   297         */        

   298         IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const TDesC8& aSetMaskData,

   299                                  TDes8& aHeaderData);

   300   

   301         /**

   302         * From MhspsMaintenanceService.

   303         */

   304         IMPORT_C ThspsServiceCompletedMessage hspsRestoreDefault(const ChspsODT& aSetMask,

   305                                    ChspsODT& aHeader);

   306 

   307         /**

   308         * From MhspsMaintenanceService.

   309         */

   310         IMPORT_C ThspsServiceCompletedMessage hspsRemoveThemeL(const ChspsODT& aSetMask);

   311         

   312         /**

   313         * GethspsResult

   314         * 

   315         * @since S60 5.0

   316         * @param aResult is a ChspsResult object containing additional information of query result.

   317         */

   318         IMPORT_C void GethspsResult(ChspsResult& aResult);

   319 

   320         /**

   321         * Returns ODT header list according to the defined search mask

   322         * 

   323         * @since S60 5.0 

   324         * @param aSearchMask is ChspsODT-object which attributes are filled to present search 

   325         *        parameters for theme set queried by client. This parametrisation follows 

   326         *        the high-level schema. 

   327         * @param aHeaderList is an list object able to carry ChspsODT-objects. 

   328         * @return Error code

   329         */

   330         IMPORT_C TInt hspsGetHeaders(const ChspsODT& aSearchMask,

   331                                    CArrayPtrFlat<ChspsODT>& aHeaderList);

   332 

   333         /**

   334         * From MhspsMaintenanceService        

   335         */

   336         IMPORT_C ThspsServiceCompletedMessage hspsAddPlugin(

   337         		const TInt aAppUid,

   338         		const TInt aConfId,

   339         		const TInt aPluginUid,

   340         		const TInt aPosition,

   341         		TInt& aAddedPluginId 

   342         		);

   343         

   344         /**

   345         * From MhspsMaintenanceService        

   346         */

   347         IMPORT_C ThspsServiceCompletedMessage hspsRemovePlugin(

   348         		const TInt aAppUid,        		

   349         		const TInt aPluginId

   350         		);

   351 

   352         /**

   353         * From MhspsMaintenanceService        

   354         */

   355         IMPORT_C ThspsServiceCompletedMessage hspsSetActivePlugin(

   356                 const TInt aAppUid,

   357                 const TInt aPluginId

   358                 );        

   359         

   360         /**

   361          * From MhspsMaintenanceService        

   362          */

   363         IMPORT_C ThspsServiceCompletedMessage hspsSetPluginSettings(

   364                const ChspsODT& aHeader,

   365                const TInt aPluginId,

   366                ChspsDomDocument& aDom,

   367                const TBool aPluginStoringStatus

   368                );

   369 

   370         /**

   371         * From MhspsMaintenanceService        

   372         */

   373         IMPORT_C ThspsServiceCompletedMessage hspsGetPluginOdtL(

   374         		const TInt aAppUid,        		

   375         		const TInt aPluginUid,

   376         		ChspsODT* aPluginOdt );

   377         

   378         /**

   379         * From MhspsMaintenanceService        

   380         */

   381         IMPORT_C ThspsServiceCompletedMessage hspsMovePluginsL(

   382         		const TInt aAppUid,        

   383         		const TInt aConfId,

   384         		const CArrayFixFlat<TInt>& aPluginIdList 

   385         		);

   386 

   387         /**

   388         * From MhspsMaintenanceService        

   389         */

   390         IMPORT_C ThspsServiceCompletedMessage hspsSetConfState(

   391                 const TInt aAppUid,        

   392                 const TInt aConfId,

   393                 const ThspsConfigurationState aState,

   394                 const ThspsConfStateChangeFilter aFilter

   395                 );

   396 

   397         /**

   398         * From MhspsMaintenanceService        

   399         */

   400         IMPORT_C ThspsServiceCompletedMessage hspsRestoreActiveAppConf(

   401                 const TInt aAppUid,

   402                 const TInt aConfUid );

   403 

   404         /** 

   405          * Updates plugin configuration in all application configuration

   406          *  

   407          * @since S60 5.0

   408          * @param apluginUid identifies the plugin configuration                

   409          * @return ThspsServiceCompletedMessage expressing the result of the call.

   410          */

   411         IMPORT_C  ThspsServiceCompletedMessage hspsPluginUpdateL(

   412                           const ChspsODT& /* aOdt */ );

   413 

   414         /**

   415         * Reinstalls requested configuration

   416         * 

   417         * @since S60 5.0

   418         * @param aAppUid is interface.

   419         * @param aConfUid is ID of the reinstalled configuration.  

   420         * @return ThspsServiceCompletedMessage expressing the result of the call.

   421         */

   422         IMPORT_C ThspsServiceCompletedMessage hspsReinstallConf(

   423             TInt aAppUid, 

   424             TInt aConfUid );

   425 

   426         /** 

   427         * Internal log bus setter. Empty method in product builds.

   428         * 

   429         * @since S60 5.0

   430         * @param aLogBus    Log bus to be set.

   431         */

   432         IMPORT_C void SetLogBus( void* aLogBus );        

   433         

   434         /**

   435         * From MhspsMaintenanceService        

   436         */                               

   437         IMPORT_C ThspsServiceCompletedMessage hspsReplacePlugin(

   438                 const TInt aAppUid,

   439                 const TInt aPluginId,             

   440                 const TInt aConfUid );

   441         

   442     protected: // Functions from base classes

   443 

   444         /**

   445         * From CActive, RunL.

   446         * Callback function.

   447         * Invoked to handle responses from the server.

   448         */

   449         void RunL();

   450 

   451         /**

   452         * From CActive, DoCancel.

   453         * Cancels any outstanding operation.

   454         */

   455         void DoCancel();

   456         

   457         /**

   458         * From CActive Called when asynchronous request has failed

   459         * @since S60 3.1

   460         */

   461         TInt RunError( TInt aError );

   462         

   463         

   464     private: 

   465        

   466         /**

   467         * Updates iResult 

   468         * @param aResultData Result data

   469         */

   470         void UpdatehspsResult( TDesC8& aResultData );

   471         

   472         /**

   473         * Creates a header object from header data (iHeaderData) 

   474         * and adds created header to the header list (iHeaderList)

   475         * @param aHeaderData Header data

   476         */

   477         void AppendHeaderListL( TDesC8& aHeaderData );

   478         

   479         /**

   480         * Gets file handle and streams odt from the file.

   481         * @since S60 5.0

   482         * 

   483         * @param aOdtPath - odt file path

   484         * @param aAppUid - application uid for accessing to the file

   485         * @param aPluginOdt - odt for streaming

   486         * @return error code  

   487         */

   488         TInt StreamOdtL( TDes& aOdtPath, 

   489         		const TInt aAppUid, ChspsODT* aPluginOdt );

   490         

   491     private: // Constructors and destructors

   492 

   493         /**

   494         * ChspsClient.

   495         * Performs the first phase of two phase construction.

   496         * @param aObserver The object to be used to handle updates from the server.

   497         */

   498         ChspsClient( MhspsThemeManagementServiceObserver& aObserver);

   499 

   500         /**

   501         * ConstructL.

   502         * Performs the second phase construction of a ChspsClient object.

   503         */

   504         void ConstructL();

   505 

   506    

   507     private: // Members

   508     

   509         /**

   510         * iSession, the theme server session.

   511         */

   512         RhspsClientSession iSession;

   513 

   514         /**

   515         * iObserver, observer which handles updates from the server.

   516         */

   517         MhspsThemeManagementServiceObserver& iObserver;

   518         

   519         /**

   520         * Message to cancel outstanding request.

   521         */

   522         ThspsServiceRequestMessage iCancelRequestMessage;

   523         

   524     private: // Data    

   525         

   526         /**

   527         * An pointer array given by service requester to be filled with headers.

   528         */

   529         CArrayPtrSeg<HBufC8>* iHeaderDataList;

   530         

   531         CArrayPtrFlat<ChspsODT>* iHeaderList; 

   532         

   533         TBuf8<KMaxHeaderDataLength8> iHeaderData;

   534         TBuf8<KMaxResultDataLength8> iResultData;

   535         

   536         TBool iODTMode;

   537         

   538         ChspsODT* iOdt;

   539         ChspsODT* iHeader;

   540         

   541         HBufC8* iSearchMaskData;

   542         HBufC8* iSetMaskData;

   543         ChspsResult* iResult;

   544         TBool iSubscription;

   545         

   546 #ifdef HSPS_LOG_ACTIVE

   547         /**

   548          * Log bus.

   549          */        

   550         ChspsLogBus* iLogBus;

   551 #endif        

   552      };

   553 

   554 

   555 #endif //__ChspsCLIENT_H__

   556 

   557 // End of File