--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/appinstall_plat/sifui_api/inc/sifui.h Tue Aug 31 15:21:33 2010 +0300
@@ -0,0 +1,290 @@
+/*
+* Copyright (c) 2010 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: CSifUi API can be used to implement UI dialogs for
+* SIF (Software Install Framework) plugins.
+*/
+
+
+/**************************************************************
+ * *
+ * WARNING - WORK-IN-PROGRESS - THIS API MAY STILL CHANGE *
+ * *
+ **************************************************************/
+
+#ifndef C_SIFUI_H
+#define C_SIFUI_H
+
+#include <e32base.h> // CBase
+#include <bamdesca.h> // MDesCArray
+
+class CSifUiPrivate;
+class CApaMaskedBitmap;
+class CSifUiCertificateInfo;
+class CSifUiAppInfo;
+class CSifUiErrorInfo;
+
+namespace Swi {
+ class CAppInfo;
+ class CCertificateInfo;
+}
+
+
+/**
+ * CSifUi provides UI dialogs for SW installation. UI dialogs are
+ * global and they can be used in a non-UI code (like SIF plugins).
+ * SW install device dialog plugin implements the UI dialogs.
+ *
+ * @lib sifui.lib
+ * @since 10.1
+ */
+class CSifUi : public CBase
+ {
+ public: // constructor and destructor
+ /**
+ * Creates new CSifUi object and pushes it into cleanup stack.
+ * @returns CSifUi* -- new CSifUi object
+ */
+ IMPORT_C static CSifUi* NewLC();
+
+ /**
+ * Creates new CSifUi object.
+ * @returns CSifUi* -- new CSifUi object
+ */
+ IMPORT_C static CSifUi* NewL();
+
+ /**
+ * Destructor.
+ */
+ ~CSifUi();
+
+ public: // new functions
+
+ //=================================================
+ // Preparing note method
+ //=================================================
+
+ /**
+ * Displays installation dialog with "Preparing" text and indefinite progress bar.
+ * No buttons are available. Use ShowConfirmationL() method to update the dialog
+ * content to the installation confirmation query.
+ */
+ IMPORT_C void ShowPreparingL();
+
+
+ //=================================================
+ // Install confirmation query methods
+ //=================================================
+
+ /**
+ * Defines memory selection alternatives for the ShowConfirmationL() installation
+ * confirmation query. Use SelectedDrive() method to get the selected drive number
+ * after ShowConfirmationL() call.
+ * @param aDriveNumbers - options for memory selection
+ */
+ IMPORT_C void SetMemorySelectionL( const RArray<TInt>& aDriveNumbers );
+
+ /**
+ * Defines certificate details for the ShowConfirmationL() installation
+ * confirmation query. If certificates are not set, then application is
+ * untrusted.
+ * @param aCertificates - certificate details
+ */
+ IMPORT_C void SetCertificateInfoL(
+ const RPointerArray<CSifUiCertificateInfo>& aCertificates );
+
+ /**
+ * Displays installation confirmation query and waits for user response.
+ * Returns ETrue if the user accepted the query. The next ShowProgressL() call
+ * changes the dialog content to installation progress note. And finally,
+ * ShowCompleteL() or ShowFailedL() call changes the dialog content to the
+ * complete or error note.
+ * If preparing installation note needs to be displayed before confirmation query,
+ * then call ShowPreparingL() before any other functions.
+ * If the installation confirmation query should contain memory selection option,
+ * then set the selectable drives with SetMemorySelectionL() first. User selected
+ * drive can be retrieved with SelectedDrive() after ShowConfirmationL() returns.
+ * If the installation confirmation query should contain certificate details, then
+ * set the certificate details using SetCertificateInfoL() first.
+ * @param aAppInfo - application information (name, size, version, vendor, icon)
+ * @return TBools - ETrue if the user accepted the query, EFalse otherwise
+ */
+ IMPORT_C TBool ShowConfirmationL( const CSifUiAppInfo& aAppInfo );
+
+ /**
+ * Gets the selected drive where new component should be installed.
+ * Use RFs::DriveToChar() to convert the drive number to drive letter.
+ * @param aDriveNumber - selected drive number
+ * @return TInt - KErrNone if successful, otherwise Symbian error code
+ */
+ IMPORT_C TInt SelectedDrive( TInt& aDriveNumber );
+
+
+ //=================================================
+ // Progress note methods
+ //=================================================
+
+ /**
+ * Installing phases in progress notes. Indicated in progress note title text.
+ */
+ enum TInstallingPhase {
+ EInstalling,
+ EDownloading,
+ ECheckingCerts
+ };
+
+ /**
+ * Displays installation progress note. Changes confirmation query content
+ * to progress note. If the progress note is already displayed, then updates
+ * the dialog content. Use IncreaseProgressBarValueL() method to increase the
+ * progress bar value.
+ * Dialog remains on the screen after progress bar shows full 100% value.
+ * Use ShowCompleteL() or ShowFailedL() methods to show the result.
+ * @param aAppInfo - application information (name, size, version, vendor, icon)
+ * @param aProgressBarFinalValue - final value of the progress bar
+ * @param aPhase - defines new title text for the progress note dialog
+ */
+ IMPORT_C void ShowProgressL( const CSifUiAppInfo& aAppInfo, TInt aProgressBarFinalValue,
+ TInstallingPhase aPhase = EInstalling );
+
+ /**
+ * Updates the progress bar value displayed in progress note. Initially progress bar
+ * shows 0%. Each aIncrement increases the value displayed in progress bar. When all
+ * increments reach the final value defined in ShowProgressNoteL() method, then the
+ * progress bar shows full 100%. Caller should check using IsCancelled() method if
+ * the user has cancelled the progress note before updating the progress bar value.
+ * @param aIncrement - progress bar value increment
+ */
+ IMPORT_C void IncreaseProgressBarValueL( TInt aIncrement );
+
+ /**
+ * Returns ETrue if the user has cancelled the progress dialog.
+ * @return TBool - ETrue if the progress dialog has been cancelled
+ */
+ IMPORT_C TBool IsCancelled();
+
+
+ //=================================================
+ // Final complete and error notes
+ //=================================================
+
+ /**
+ * Displays installation complete note and waits for the user to close it.
+ * Installation complete note contains "Show" button to show installed
+ * applications in application library. Use SetButtonVisible() method to
+ * hide the "Show" button when necessary.
+ */
+ IMPORT_C void ShowCompleteL();
+
+ /**
+ * Displays installation error note and waits for user to close it.
+ * Installation error note contains "Details" button to show the detailed
+ * error message (when available). Also SetButtonVisible() method can be
+ * used to hide the "Details" button if necessary.
+ * @param aErrorCategory - error category
+ * @param aErrorMessage - localized error message to be displayed
+ * @param aErrorDetails - localized error message details (if any)
+ * @param aErrorCode - error code
+ * @param aErrorCode - error code
+ */
+ IMPORT_C void ShowFailedL( const CSifUiErrorInfo& aErrorInfo );
+
+
+ //=================================================
+ // Buttons in progress/complete/error notes
+ //=================================================
+
+ /**
+ * Toolbar buttons in progress and complete notes that can be disabled/hidden.
+ */
+ enum TOptionalButton
+ {
+ EHideProgressButton, // "Hide" button in progress note
+ ECancelProgressButton, // "Cancel" button in progress note
+ EShowInAppLibButton, // "Show" button in complete note
+ EErrorDetailsButton // "Details" button in error note
+ };
+
+ /**
+ * Hides or shows optional toolbar buttons from installation progress note
+ * or installation complete note. All optional buttos are visible by default.
+ * Buttons visibility becomes effective in the next ShowProgressL(),
+ * ShowCompleteL(), or IncreseProgressBarValueL() method calls.
+ * @param aButton - button which visibility is changed
+ * @param aIsVisible - EFalse if button needs to be hidden
+ */
+ IMPORT_C void SetButtonVisible( TOptionalButton aButton, TBool aIsVisible );
+
+
+ //=================================================
+ // Other query dialogs
+ //=================================================
+
+ /**
+ * Displays dialog requesting capabilities for the application being installed
+ * and waits for user response. Returns ETrue if the user granted the capabilities.
+ * Other dialogs (like progress note) are not affected.
+ * @param aCapabilities - requested user capabilities
+ * @return TBool - ETrue if the user granted the capabilities, EFalse otherwise
+ */
+ IMPORT_C TBool ShowGrantCapabilitiesL( const TCapabilitySet& aCapabilities );
+
+ /**
+ * Displays pop-up language selection dialog with radio-buttons, and
+ * waits for user response. Other displayed installation dialogs (like
+ * progress note) are not affected. Returns integer that is the index
+ * of the selected language in given langauge array, or error code.
+ * Return value is KErrCancel if the user cancelled the query.
+ * @param aLanguages - array of selectable languages
+ * @return The selected item index to aLangauges array, or error code.
+ */
+ IMPORT_C TInt ShowSelectLanguageL( const RArray<TLanguage>& aLanguages );
+
+ /**
+ * Displays multi-selection pop-up dialog with checkboxes, and waits
+ * for user response. Other displayed installation dialogs (like progress
+ * note) are not affected. Returns ETrue if the user made the selection,
+ * EFalse if the user cancelled the query. Selected indices are returned
+ * in aSelectedIndexes array.
+ * @param aSelectableItems - array of selectable items displayed
+ * @param aSelectedIndexes - returns the selected item indices
+ * @return TBool - ETrue if the user accepted the query, EFalse otherwise
+ */
+ IMPORT_C TBool ShowSelectOptionsL( const MDesCArray& aSelectableItems,
+ RArray<TInt>& aSelectedIndexes );
+
+
+ //=================================================
+ // DEPRECATED METHODS
+ //=================================================
+
+ // DEPRECATED, WILL BE REMOVED, DO NOT USE
+ IMPORT_C void ShowFailedL( TInt aErrorCode, const TDesC& aErrorMessage,
+ const TDesC& aErrorDetails = KNullDesC );
+ IMPORT_C TBool ShowSingleSelectionL( const TDesC& aTitle,
+ const MDesCArray& aSelectableItems, TInt& aSelectedIndex );
+ IMPORT_C TBool ShowMultiSelectionL( const TDesC& aTitle,
+ const MDesCArray& aSelectableItems, RArray<TInt>& aSelectedIndexes );
+
+
+ private: // new functions
+ CSifUi();
+ void ConstructL();
+
+ private: // data
+ CSifUiPrivate* iPrivate;
+ };
+
+
+#endif // C_SIFUI_H
+