--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/homescreenpluginsrv/inc/hspsclient.h Thu Dec 17 08:54:17 2009 +0200
@@ -0,0 +1,557 @@
+/*
+* Copyright (c) 2008 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:
+*
+* ChspsClient is a client-side implementation of MhspsInstallationService and MhspsMaintenanceService
+* interface definitions of Homescreen Plugin Configuration Managament Services APIs. Installation and
+* Maintenance Services are intended to serve Homescreen as well as S60 legacy applications - especially
+* the Personalisation Application - with the plugin installation and maintenance
+* functionality. Typical use-case is that client application initiates ChspsClient-object, connects
+* to hspsThemeServer with its application UID, and commences installation and maintenance service
+* requests.
+*
+* Security in using services is quarantied by controlling the rights to see Application Themes
+* and operate with hsps Theme Server. This control is based on SECUREID of application process.
+* Security is maintained behind the curtain by means of Symbian EKA2 Kernel services for Platform
+* Security.
+*
+* ChspsClient offers high- and low-level API-functionality. High-level and low-level calls are
+* diffrentiated by their parametrization. High-level parametrization is directed to the be used by
+* applications which need human readable data and offer a user interface. Low-level parametrization
+* is directed to the machine-originated requestors like OTA Push or DM (Device Management)
+* sub-systems where data is not needed to understand semanticly.
+* ChspsClient delegates server messages to its client application by
+* MhspsThemeManagementServiceObserver::HandlehspsClientMessage() call-back to be implemented by the
+* client application.
+*
+* Theme Installation Services
+* ===========================
+* Processing a installation task works in asynchronous mode, however, synchronous mode is applied
+* everytime the installation is initiated. After checking installation rights and files validities,
+* hsps Theme Server will allow actual installation. Client application must call actual
+* installation by commencing next phase execution explicitly. First call of installation returns
+* the ODT-header of the theme to be installed. This is to enable previewing information about
+* a theme to be installed. In this point, user can accept or decline the installation.
+* Installation preview feature is useful especially in OTA-service cases when user acception on
+* theme installation might be selected a a part of user policy settings.
+* A theme can include resources that can be imported to the target system as such like some audio
+* files etc., however, most of the images must be fitted on to the target device's color depth and
+* pixel density. In these cases, the needed conversions will be executed asynchronously on
+* server-side. Asynchronous installation is executed in phases - resource by resource.
+* Installation phases are promoted automaticly, however, client application can control and
+* monitor installation phases, and also cancel installation at any time. If installation is
+* cancelled, hspsThemeServer initiates roll-back functionality removing inconsistent installation.
+*
+* Theme Maintenanace Services:
+* ============================
+* Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().
+* Others functions are straightforward to use. They are explained in the class declaration section
+* below. The asynchronous service is applied only in theme listing service calls.
+* Client application initiates the theme listing by calling synchronous function
+* hspsGetListHeaders(). This call initiates the query. Client application should call
+* hspsGetNextHeader() after checking that any themes matching on current query is found or that query
+* is valid at least. This action is called a subscription. To receive actual theme listing, the
+* client application must start to listen call-back messages from the server about list delivery.
+* The headers matching on query will be delivered immediately. Query remains until
+* hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository,
+* it will be delivered if the query concers it.
+*
+*
+*
+*/
+
+
+#ifndef __ChspsCLIENT_H__
+#define __ChspsCLIENT_H__
+
+#include <e32base.h>
+
+#include "hspsthememanagement.h"
+#include "hspsclientsession.h"
+#include "hspsresult.h"
+
+#ifdef HSPS_LOG_ACTIVE
+class ChspsLogBus;
+#endif
+
+/** hspsClient Panic Category. */
+_LIT( KhspsClient, "hspsClient" );
+
+/** hspsClient panic codes: */
+enum ThspsClientPanics
+ {
+ EhspsClientBadState
+ };
+
+class RhspsClientSession;
+class MhspsInstallationService;
+class MhspsMaintenanceService;
+class MhspsThemeManagementServiceObserver;
+class ChspsODT;
+class ChspsResult;
+
+/**
+ * ChspsClient.
+ * ChspsClient performs all client-side theme installation and maintenance related functionality.
+ * Theme maintenance services includes theme listings, theme activation, theme removal, and default
+ * theme restoring functionality.
+ *
+ * Class inheritance:
+ * ==================
+ * ChspsClient derives CActive for asynchronous request handling, and MhspsInstallationService and
+ * MhspsMaintenanceService from Homescreenpluginservices.
+ *
+ * Theme installation functionality:
+ * =================================
+ * Client application must call hspsInstallNextPhaseL() after testing that the synchronous call
+ * hspsInstallTheme() has returned EhspsInstallPhaseSuccess return code signalling that actual
+ * installation is allowed. The rest of the installation phases will be executed automatically,
+ * however, installation can be interrupted by calling hspsCancelInstallTheme() at any time.
+ * If installation is canceled, hspsThemeServer initiates roll-back functionality removing
+ * inconsistent installation.
+ * Installation service uses specific manifest-file format to get informed about the xml, css,
+ * dtd, and resource files to be installed. Resource files might be locale-specific or generic
+ * as well.
+ * hspsThemeServer takes care of saving everything on their appropriate places in the target device's
+ * user disk. Theme storage is located in hspsThemeServer's private-folder.
+ * Locales are instructed in manifest file also. Manifest file's file-extension must be .dat,
+ * but actually, the file-name can be whatever, however, when low-level parametrization is used,
+ * the name must be "manifest.dat" and it must be the last file extracted from the installation
+ * package.
+ * For more information of manifest-file format, see Homescreen wikipages.
+ *
+ * Installation functions can return one of the following ThspsServiceCompletedMessage-codes:
+ * - EhspsInstallThemeSuccess,
+ * - EhspsInstallPhaseSuccess, or
+ * - EhspsInstallThemeFailed.
+ *
+ * Client application must implement MhspsThemeManagementServiceObserver-interface and listen these
+ * messages mentioned. Let it be emphasised that both synchronous and asynchronous calls can return
+ * the codes above. Installation functions may also return one of the following codes:
+ * - EhspsServiceRequestSheduled, or
+ * - EhspsServiceRequestError.
+ *
+ * For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.
+ *
+ * Theme maintenance functionality:
+ * ================================
+ * Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().
+ * Others functions are straightforward to use but hspsGetListHeaders(). This will be explained next;
+ * synchronous call hspsGetListHeaders() initiates the theme header listing by passing search mask
+ * to HSPS Server's Maintenance Service. This search mask is called a query. It also passes
+ * a list object in where maintenance service should append theme-header objects (type of
+ * ChspsODT-class without DOM-document) when one is retrieved asychronously. Search mask should be
+ * filled with proper parameters matching the need in hand. If no parameters are given, all headers
+ * of Application Themes available in Definition Repository will be delivered, otherwise,
+ * only sub-set of theme-headers will be delivered. After the query-call hspsGetListHeaders(), the
+ * delivering of the theme-headers is asynchronous. Asynchronous service must be initiated by
+ * calling hspsGetNextHeader() after checking that any theme matching on current query is found or
+ * that query is valid anyway. This action is called a subscription. To receive theme
+ * listing, the client application must implement MhspsThemeManagementServiceObserver-interface and
+ * start to listen call-back messages.
+ * The headers matching on query will be delivered immediately. Query remains until
+ * hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, it
+ * will be delivered. As mentioned, when hspsGetListHeaders() returns, the return value must be checked.
+ * Return value could be one of the following:
+ * - EhspsGetListHeadersSuccess - there is at least one Application Theme available matching on query.
+ * Call first hspsGetNextHeader() to get the headers. Same call will set
+ * the subscribtion of new ones possible coming available later.
+ * - EhspsGetListHeadersEmpty - there is no themes matching on the query available at the time,
+ * however, some might be exist later in due to installations.
+ * Client application should retain the subcription.
+ * - EhspsGetListHeadersFailed - service request failed for some reason. Possible reasons are for e.g.
+ * the missing rights to list headers queried.
+ *
+ * Additional Return Code Support (ChspsResult) will express for e.g. the number of headers to be
+ * delivered or possible system error code in failed cases.
+ *
+ * By MhspsServiceObserver::HandlehspsServiceMessage() call-back function implementation, client
+ * application must listen the following ThspsServiceCompletedMessage-messages:
+ *
+ * - EhspsGetListHeadersUpdate - header list on the client side has a new object appended at the end
+ * of the list,
+ * - EhspsGetListHeadersRestart - header list on server side has changed so much that the client must
+ * empty the list printed on screen. New list will be delivered
+ * immediately. The subscription stands.
+ * - EhspsGetListHeadersEmpty - header list on server side is now empty. The client must empty
+ * the list on screen if printed. The subscription stands.
+ * - EhspsGetListHeadersFailed - operation has failed. Client should cancel request and restart.
+ *
+ * Maintenanace functions may also return one of the following codes:
+ * - EhspsServiceRequestSheduled, or
+ * - EhspsServiceRequestError.
+ *
+ * For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.
+ *
+ *
+ * @lib hspsClient.lib
+ * @since S60 5.0
+ * @ingroup group_hspsclients
+ */
+class ChspsClient : public CActive, public MhspsInstallationService, public MhspsMaintenanceService
+ {
+ public: // Constructors and destructors
+ /**
+ * NewL.
+ *
+ * Two-phased constructor.
+ * Creates a ChspsClient object using two phase construction,
+ * and return a pointer to the created object.
+ *
+ * @since S60 5.0
+ * @param aObserver The object to be used to handle updates from the server.
+ */
+ IMPORT_C static ChspsClient* NewL(MhspsThemeManagementServiceObserver& aObserver );
+
+ /**
+ * NewLC.
+ *
+ * Two-phased constructor.
+ * Creates a ChspsClinet object using two phase construction,
+ * and return a pointer to the created object.
+ *
+ * @since S60 5.0
+ * @param aObserver The object to be used to handle updates from the server.
+ */
+ IMPORT_C static ChspsClient* NewLC( MhspsThemeManagementServiceObserver& aObserver );
+
+ /**
+ * ~ChspsClient.
+ *
+ * Destructor.
+ * Destroys the object and release all memory objects.
+ */
+ virtual ~ChspsClient();
+
+ public: // New functions
+
+ /**
+ * From MhspsInstallationService.
+ */
+
+ IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName,
+ ChspsODT& aHeader);
+
+ /**
+ * From MhspsInstallationService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName,
+ TDes8& aHeaderData);
+
+ /**
+ * From MhspsInstallationService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(ChspsODT& aHeader);
+
+ /**
+ * From MhspsInstallationService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(TDes8& aHeaderData);
+
+ /**
+ * From MhspsInstallationService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsCancelInstallTheme();
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const ChspsODT& aSearchMask,
+ CArrayPtrFlat<ChspsODT>& aHeaderList);
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const TDesC8& aSearchMaskData,
+ CArrayPtrSeg<HBufC8>& aHeaderDataList);
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsGetNextHeader();
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsCancelGetListHeaders();
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const ChspsODT& aSetMask,
+ ChspsODT& aHeader);
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const TDesC8& aSetMaskData,
+ TDes8& aHeaderData);
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsRestoreDefault(const ChspsODT& aSetMask,
+ ChspsODT& aHeader);
+
+ /**
+ * From MhspsMaintenanceService.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsRemoveThemeL(const ChspsODT& aSetMask);
+
+ /**
+ * GethspsResult
+ *
+ * @since S60 5.0
+ * @param aResult is a ChspsResult object containing additional information of query result.
+ */
+ IMPORT_C void GethspsResult(ChspsResult& aResult);
+
+ /**
+ * Returns ODT header list according to the defined search mask
+ *
+ * @since S60 5.0
+ * @param aSearchMask is ChspsODT-object which attributes are filled to present search
+ * parameters for theme set queried by client. This parametrisation follows
+ * the high-level schema.
+ * @param aHeaderList is an list object able to carry ChspsODT-objects.
+ * @return Error code
+ */
+ IMPORT_C TInt hspsGetHeaders(const ChspsODT& aSearchMask,
+ CArrayPtrFlat<ChspsODT>& aHeaderList);
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsAddPlugin(
+ const TInt aAppUid,
+ const TInt aConfId,
+ const TInt aPluginUid,
+ const TInt aPosition,
+ TInt& aAddedPluginId
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsRemovePlugin(
+ const TInt aAppUid,
+ const TInt aPluginId
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsSetActivePlugin(
+ const TInt aAppUid,
+ const TInt aPluginId
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsSetPluginSettings(
+ const ChspsODT& aHeader,
+ const TInt aPluginId,
+ ChspsDomDocument& aDom,
+ const TBool aPluginStoringStatus
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsGetPluginOdtL(
+ const TInt aAppUid,
+ const TInt aPluginUid,
+ ChspsODT* aPluginOdt );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsMovePluginsL(
+ const TInt aAppUid,
+ const TInt aConfId,
+ const CArrayFixFlat<TInt>& aPluginIdList
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsSetConfState(
+ const TInt aAppUid,
+ const TInt aConfId,
+ const ThspsConfigurationState aState,
+ const ThspsConfStateChangeFilter aFilter
+ );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsRestoreActiveAppConf(
+ const TInt aAppUid,
+ const TInt aConfUid );
+
+ /**
+ * Updates plugin configuration in all application configuration
+ *
+ * @since S60 5.0
+ * @param apluginUid identifies the plugin configuration
+ * @return ThspsServiceCompletedMessage expressing the result of the call.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsPluginUpdateL(
+ const ChspsODT& /* aOdt */ );
+
+ /**
+ * Reinstalls requested configuration
+ *
+ * @since S60 5.0
+ * @param aAppUid is interface.
+ * @param aConfUid is ID of the reinstalled configuration.
+ * @return ThspsServiceCompletedMessage expressing the result of the call.
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsReinstallConf(
+ TInt aAppUid,
+ TInt aConfUid );
+
+ /**
+ * Internal log bus setter. Empty method in product builds.
+ *
+ * @since S60 5.0
+ * @param aLogBus Log bus to be set.
+ */
+ IMPORT_C void SetLogBus( void* aLogBus );
+
+ /**
+ * From MhspsMaintenanceService
+ */
+ IMPORT_C ThspsServiceCompletedMessage hspsReplacePlugin(
+ const TInt aAppUid,
+ const TInt aPluginId,
+ const TInt aConfUid );
+
+ protected: // Functions from base classes
+
+ /**
+ * From CActive, RunL.
+ * Callback function.
+ * Invoked to handle responses from the server.
+ */
+ void RunL();
+
+ /**
+ * From CActive, DoCancel.
+ * Cancels any outstanding operation.
+ */
+ void DoCancel();
+
+ /**
+ * From CActive Called when asynchronous request has failed
+ * @since S60 3.1
+ */
+ TInt RunError( TInt aError );
+
+
+ private:
+
+ /**
+ * Updates iResult
+ * @param aResultData Result data
+ */
+ void UpdatehspsResult( TDesC8& aResultData );
+
+ /**
+ * Creates a header object from header data (iHeaderData)
+ * and adds created header to the header list (iHeaderList)
+ * @param aHeaderData Header data
+ */
+ void AppendHeaderListL( TDesC8& aHeaderData );
+
+ /**
+ * Gets file handle and streams odt from the file.
+ * @since S60 5.0
+ *
+ * @param aOdtPath - odt file path
+ * @param aAppUid - application uid for accessing to the file
+ * @param aPluginOdt - odt for streaming
+ * @return error code
+ */
+ TInt StreamOdtL( TDes& aOdtPath,
+ const TInt aAppUid, ChspsODT* aPluginOdt );
+
+ private: // Constructors and destructors
+
+ /**
+ * ChspsClient.
+ * Performs the first phase of two phase construction.
+ * @param aObserver The object to be used to handle updates from the server.
+ */
+ ChspsClient( MhspsThemeManagementServiceObserver& aObserver);
+
+ /**
+ * ConstructL.
+ * Performs the second phase construction of a ChspsClient object.
+ */
+ void ConstructL();
+
+
+ private: // Members
+
+ /**
+ * iSession, the theme server session.
+ */
+ RhspsClientSession iSession;
+
+ /**
+ * iObserver, observer which handles updates from the server.
+ */
+ MhspsThemeManagementServiceObserver& iObserver;
+
+ /**
+ * Message to cancel outstanding request.
+ */
+ ThspsServiceRequestMessage iCancelRequestMessage;
+
+ private: // Data
+
+ /**
+ * An pointer array given by service requester to be filled with headers.
+ */
+ CArrayPtrSeg<HBufC8>* iHeaderDataList;
+
+ CArrayPtrFlat<ChspsODT>* iHeaderList;
+
+ TBuf8<KMaxHeaderDataLength8> iHeaderData;
+ TBuf8<KMaxResultDataLength8> iResultData;
+
+ TBool iODTMode;
+
+ ChspsODT* iOdt;
+ ChspsODT* iHeader;
+
+ HBufC8* iSearchMaskData;
+ HBufC8* iSetMaskData;
+ ChspsResult* iResult;
+ TBool iSubscription;
+
+#ifdef HSPS_LOG_ACTIVE
+ /**
+ * Log bus.
+ */
+ ChspsLogBus* iLogBus;
+#endif
+ };
+
+
+#endif //__ChspsCLIENT_H__
+
+// End of File