diff -r 000000000000 -r 16d8024aca5e src/hbcore/devicedialogbase/hbdevicedialogplugin.cpp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/hbcore/devicedialogbase/hbdevicedialogplugin.cpp Mon Apr 19 14:02:13 2010 +0300 @@ -0,0 +1,537 @@ +/**************************************************************************** +** +** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (developer.feedback@nokia.com) +** +** This file is part of the HbCore module of the UI Extensions for Mobile. +** +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this file. +** Please review the following information to ensure the GNU Lesser General +** Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at developer.feedback@nokia.com. +** +****************************************************************************/ + +/*! + \class HbDeviceDialogPlugin + \brief HbDeviceDialogPlugin is an abstract base class for device dialog widget plugins. + + Device dialogs are widgets which are shown on top of all applications by a device dialog + service. The service queues and displays device dialogs according to client requests and + system state. The service displays widgets in it's window (HbApplication window). + + Device dialog widgets are created by plugins. The service loads a plugin to create and display + a device dialog. A single plugin may implement several different dialogs or just one. + Dialogs are identified by a string. By convention the string should follow + inverted domain name format. For example com.nokia.hb.devicedialog.note/1.0. + Function deviceDialogTypes() returns a list of dialog types the plugin implements. + + Appending version number into device dialog type string enables versioning of device dialogs. + A plugin should handle versioning by returning device dialog type string for all versions it + implements in deviceDialogTypes() and then in createDeviceDialog() create a device dialog + instance compatible with the version requested. This could always be the latest version if it + is backwards compatible with older versions. Device dialog framework is unaware of version + numbers in type strings. It performs string comparison of the whole string when searching + for a plugin. + + Device dialogs are divided into three groups: generic device dialog, device notification dialog + and indicator groups. The group dictates how and when a dialog is shown. Each dialog + indicates which group it belongs to. The group need not be fixed. It may change depending on + create parameters. + + Device dialog groups may prioritize (queueing) device dialogs in respect to other groups. + In addition each device dialog has an individual queueing priority that may affect how it is + shown inside a group. Currently there is no queueing implemented for device dialogs. All + dialogs are displayed in order requests are received. Z-order of dialogs on display is + determined by popup framework. Last dialog created is on top. Z-order may be changed by + dialog widget changing it's popup priority. + + Device dialog widgets have to be derived from HbPopup either directly or by ancestry. + +
+ For future needs. Not implemented. + Device dialog may be shared by several device dialog clients. Each client can update the + device dialog and receive signals from it equally. Clients attach to a shared device dialog + instance by agreeing on an unique tag. The tag is appended into device dialog type with a % + separator. For example here the tag "#1" is appended into device dialog type + "hb.devicedialog.note/1.0%#1". If a device dialog instance exists, a client is attached into it + instead of creating a new one. To allow sharing, plugin must set + HbDeviceDialogPlugin::SharedDeviceDialog. +
+ + On S60, platform and third party plugins are run by separate servers with different + platform security capabilities. The capabilities are following. + - Platform plugins + - ProtServ, SwEvent, TrustedUI + - Third party plugins + - ProtServ, TrustedUI + + Plugins are responsible for maintaining system security for their own part. If plugin + performs operations that may compromise security or want's to limit access to specific + clients, it should check client security credentials in accessAllowed() function. + Device dialog framework calls this function before creating or attaching client to a + plugin if HbDeviceDialogPlugin::SecurityCheck is set. Access is denied if the + function returns false. In addition, HbDeviceDialogPlugin constructor has a check which + allows only device dialog service to load plugins derived from it. + + Device dialog plugins can be installed into a device by users. Tbd. This needs to be clarified. + + Plugin location differs depending on platform. On Symbian, device dialog plugin stubs are + located in /resource/plugins/devicedialogs directory and executables in /sys/bin directory. + On Windows/Linux plugin executables are searched from application's current directory and + HB_PLUGINS_DIR/devicedialogs directory. + + Creating a device dialog plugin and widget involves following steps. + - Set in .pro file TEMPLATE = lib and CONFIG += hb plugin + - Derive a class from HbPopup or derivatives and HbDeviceDialogInterface + \code + class HbSampleMessageBoxWidget : public HbMessageBox, public HbDeviceDialogInterface + { + Q_OBJECT + \endcode + - Implement device dialog widget and HbDeviceDialogInterface interface. Declare and emit + deviceDialogClosed and optionally deviceDialogData signals. + \code + public: + bool setDeviceDialogParameters(const QVariantMap ¶meters); + int deviceDialogError() const; + void closeDeviceDialog(bool byClient); + HbPopup *deviceDialogWidget() const; + signals: + void deviceDialogClosed(); + void deviceDialogData(QVariantMap data); + \endcode + - Wrap the widget into a plugin derived from HbDeviceDialogPlugin + \code + class HbSampleMessageBoxPlugin : public HbDeviceDialogPlugin + { + Q_OBJECT + \endcode + - Implement HbDeviceDialogPlugin pure virtual functions + \code + bool accessAllowed(const QString &deviceDialogType, + const QVariantMap ¶meters, const QVariantMap &securityInfo) const; + HbDeviceDialogInterface *createDeviceDialog(const QString &deviceDialogType, const QVariantMap ¶meters); + bool deviceDialogInfo(const QString &deviceDialogType, + const QVariantMap ¶meters, DeviceDialogInfo *info) const; + QStringList deviceDialogTypes() const; + PluginFlags pluginFlags() const; + int error() const; + \endcode + + Class diagram of the sample plugin: + \dot + digraph G { + rankdir=LR; + + subgraph cluster_class_diagram { + style=solid; + + node [shape = box, style=solid, fontsize = 10]; + HbSampleMessageBoxPlugin [label = "HbSampleMessageBoxPlugin"]; + QObject [label = "QObject"]; + HbDeviceDialogPluginInterface [label = "HbDeviceDialogPluginInterface"]; + HbDeviceDialogPlugin [label = "HbDeviceDialogPlugin"]; + edge [fontsize = 10, style = filled]; + QObject -> HbDeviceDialogPlugin [label = "is a"]; + HbDeviceDialogPluginInterface -> HbDeviceDialogPlugin [label = "is a"]; + HbDeviceDialogPlugin -> HbSampleMessageBoxPlugin [label = "is a"]; + + HbSampleMessageBoxWidget [label = "HbSampleMessageBoxWidget"]; + HbMessageBox [label = "HbMessageBox"]; + HbDeviceDialogInterface [label = "HbDeviceDialogInterface"]; + HbMessageBox -> HbSampleMessageBoxWidget [label = "is a"]; + HbDeviceDialogInterface -> HbSampleMessageBoxWidget [label = "is a"]; + + edge [fontsize = 10, style = dotted]; + HbSampleMessageBoxPlugin -> HbSampleMessageBoxWidget [label = "creates"]; + } + + subgraph cluster_key { + label = "Key"; + style=solid; + node [shape = box, style=solid, fontsize = 10]; + Class1 [label = "Class"]; + Class2 [label = "Class"]; + Class3 [label = "Class"]; + + edge [fontsize = 10, style = filled]; + Class2 -> Class1 [label = "generalization"]; + edge [fontsize = 10, style = dotted]; + Class3 -> Class1 [label = "dependency"]; + } + } + \enddot + + Sample plugin implementations can be found in src/hbplugins/devicedialogs directory. + + \sa HbDeviceDialogPluginInterface HbDeviceDialogInterface HbDeviceDialog HbPopup + + \alpha + \hbcore +*/ + +/*! + \enum HbDeviceDialogPlugin::PluginFlag + Defines flags for the plugin. + + \sa pluginFlags +*/ +/*! + \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::NoPluginFlags + No flags specified. +*/ +/*! + \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::PreloadPlugin + Load plugin on startup. This also implies KeepPluginLoaded flag. +*/ +/*! + \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::KeepPluginLoaded + Keep the plugin loaded in memory. Flag is ignored for third party plugins. +*/ + +/*! + \enum HbDeviceDialogPlugin::DeviceDialogGroup + Defines device dialog groups. Each of these groups have different rules for showing + device dialogs. + + \sa deviceDialogInfo DeviceDialogInfo +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::GenericDeviceDialogGroup + Common device dialogs. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::DeviceNotificationDialogGroup + Device notification dialogs. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::IndicatorGroup + Indicators. Only platform device dialogs may belong to this group. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::SecurityGroup + Screen saver and alarm dialogs. Only platform device dialogs may belong to this group. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::CriticalGroup + High priority dialogs shown on top other dialogs. Only platform device dialogs may + belong to this group. +*/ + +/*! + \enum HbDeviceDialogPlugin::DeviceDialogFlag + Defines flags for a device dialog created by the plugin. + + \sa deviceDialogInfo DeviceDialogInfo +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::NoDeviceDialogFlags + No flags specified. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::SharedDeviceDialog + For future needs. Not used. + The device dialog may be shared. Several clients may share the same device dialog instance. + If the flag is not set, device dialog service doesn't allow sharing of the device dialog. + +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::SecurityCheck + If the flag is set, device dialog service calls accessAllowed() before creating or + attaching to a device dialog widget. +*/ + +/*! + \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::NoLocalisableData + If the flag is set, device dialog service does not try to find and localise strings + from the property set. If not set localisable strings are localised by the device + dialog service. + + \deprecated HbDeviceDialogPlugin::NoLocalisableData. Will be removed as localization + is always done by application. +*/ + +/*! + \var HbDeviceDialogPlugin::DefaultPriority + Default priority value to return in DeviceDialogInfo. +*/ + +/*! + \struct HbDeviceDialogPlugin::DeviceDialogInfo + \brief Structure containing device dialog widget information. + + Passed as a parameter to HbDeviceDialogPlugin::deviceDialogInfo(). + + \sa HbDeviceDialogPlugin +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogInfo::group + Group the device dialog widget belongs to. HbDeviceDialogPlugin::DeviceDialogGroup. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogInfo::flags + Device dialog flags. HbDeviceDialogPlugin::DeviceDialogFlag. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogInfo::priority + For future needs. Not used. + Device dialog display priority. Determines queuing order of dialogs. Fill with + HbDeviceDialogPlugin::DefaultPriority. +*/ +/*! + \var HbDeviceDialogPlugin::DeviceDialogInfo::spare + Spare space for future needs. +*/ + +/*! + \fn virtual bool HbDeviceDialogPlugin::accessAllowed(const QString &deviceDialogType, + const QVariantMap ¶meters, const QVariantMap &securityInfo) const = 0 + + Checks if client is allowed use the device dialog that the plugin creates. Device dialog service + calls this function before creating a device dialog or attaching into an existing one if flag + HbDeviceDialogPlugin::SecurityCheck is set. The implementation is operating system dependent. + On Symbian this may involve checking client's platform security capabilities or secure ID for + example. Returns true if client is allowed to use the device dialog. + + \param deviceDialogType Device dialog type. + \param parameters Device dialog parameters. + \param securityInfo Information for security check. Content is operating system dependent. + The format is pairs. + Currently only Symbian is defined. + + + + + + + + + + + + + + + + + + + + + + +
Symbian security information
KeyValue typeDescription
"sym-secureId"quint32Client's secure ID
"sym-vendorId"quint32Client's vendor ID
"sym-caps"quint32Client's capability set as a bitmap
+*/ + +/*! + \fn virtual bool HbDeviceDialogPlugin::deviceDialogInfo(const QString &deviceDialogType, + const QVariantMap ¶meters, DeviceDialogInfo *info) const = 0 + + Gets information of the device dialog created by the plugin. Device dialog manager calls this + function before creating the device dialog widget to check + HbDeviceDialogPlugin::DeviceDialogGroup, HbDeviceDialogPlugin::DeviceDialogFlag and priority. + Returns true if device dialog information returned is valid. + + \param deviceDialogType Device dialog type. + \param parameters Device dialog parameters. + \param info Structure the plugin fills with an information of the device dialog it + creates with the deviceDialogType and parameters. +*/ + +/*! + \fn virtual QStringList HbDeviceDialogPlugin::deviceDialogTypes() const = 0 + + Returns a list of device dialog types the plugin implements. A plugin may implement several + device dialog types. By convention device dialog type strings should follow inverted domain + name format. For example com.nokia.hb.devicedialog.note/1.0 +*/ + +/*! + \fn virtual HbDeviceDialogPlugin::Flags HbDeviceDialogPlugin::pluginFlags() const = 0 + + Returns plugin flags. +*/ + +/*! + \fn virtual int HbDeviceDialogPlugin::error() const = 0 + + Returns an error last occurred. Error code ranges are defined in HbDeviceDialog. The code is + passed to a client by device dialog framework. +*/ + +/*************************************************************************************************/ + +/*! + \class HbDeviceDialogInterface + \brief HbDeviceDialogInterface is an abstract interface class for a device dialog widget. + + Device dialogs are widgets which are shown on top of all applications by a device dialog service. + Widgets are created by plugins. Device dialog service uses this interface to update widget + parameters and close widget. + + The widget implementation must implement this interface. In addition it must provide a + deviceDialogClosed() signal and optionally deviceDialogData() signal if data needs to be + passed to a client. + + Device dialog widgets must be derived from HbPopup or derivatives as described in + HbDeviceDialogPlugin. + + Following popup convention, the widget is not visible immediately after is created. + Device dialog framework calls HbPopup::show() to display the widget. The service may change + The service may change visibility of the widget by HbPopup::setVisible function. + + The widget should close itself by either a timeout or user interaction. It may also be closed + gracefully either by system or the client by a closeDeviceDialog() function. It is assumed that + the widget object can be ungracefully destroyed (delete) at any time. + + \b Signals: + + \b void \b deviceDialogClosed() + + Device dialog widget must implement this signal. The widget should emit this signal + when it has disappeared from a display and can be deleted. It is important this signal is + emitted as device dialog service relies on it to detect the widget closing. + + \b void \b deviceDialogData(QVariantMap data) + + This signal is emitted by a device dialog widget to send data to a client. The signal + is optional. If the widget does not provide any data, the signal is not needed. \a data + contains data from the widget. The data is passed unmodified to the client. The structure + and meaning of the data is a contract between the widget and a client. + \endcode + + \sa HbDeviceDialogPlugin HbDeviceDialog + + \alpha + \hbcore +*/ + +/*! + \fn virtual bool HbDeviceDialogInterface::setDeviceDialogParameters( + const QVariantMap ¶meters) = 0 + + Set device dialog widget parameters. This function may be called after the widget is created + to update widget parameters. \a parameters contains widget parameters. The structure and + meaning of parameters is a contract between the plugin and a client. Returns true on success + or false on failure. +*/ + +/*! + \fn virtual int HbDeviceDialogInterface::deviceDialogError() const = 0 + + Returns an error last occurred. Error code ranges are defined in HbDeviceDialog. The code is + passed to a client by device dialog framework. + + \sa HbDeviceDialog::DeviceDialogError +*/ + +/*! + \fn virtual void HbDeviceDialogInterface::closeDeviceDialog(bool byClient) = 0 + + Closes a device dialog widget gracefully. This function may called due to device dialog + client calling HbDeviceDialog::cancel() or by device dialog service if it decides + that a dialog needs to be closed. Device dialog widget may also close itself without + this function being called. \a byClient is true if client initiated the closing. + Otherwise the closing was initiated by the device dialog framework. The widget may also be + deleted at any time ungracefully without closeDeviceDialog() being called. + + \sa deviceDialogClosed() +*/ + +/*! + \fn virtual HbPopup *HbDeviceDialogInterface::deviceDialogWidget() const = 0 + + Returns a pointer to a widget that implements the user interface of the device dialog. The + widget must be derived from a HbPopup or it's derivatives. + + \sa HbDeviceDialogPlugin +*/ + +/*! + \fn virtual QObject *HbDeviceDialogInterface::signalSender() const + + Returns a pointer to an object that is a sender of deviceDialogClosed() and deviceDialogData() + signals. There is a default implementation which returns null. In this case it is assumed that + the device dialog widget is the signal source. This function may be overriden for example in + a case where the dialog widget is encapsulated by a container class which sends the required + signals. Note that there has to be one to one relationship between the widget and the sender. + I.e. there is a one sender object per widget. + + \sa deviceDialogWidget deviceDialogClosed() deviceDialogData() +*/ + +/*************************************************************************************************/ + +/*! + \class HbDeviceDialogPluginInterface + \brief HbDeviceDialogPluginInterface is an abstract interface that identifies a device dialog plugin. + + This class is not intended for direct derivation. Instead a device dialog plugin should be derived + from HbDeviceDialogPlugin. This class declares createDeviceDialog() function which the plugin must + implement. + + \alpha + \hbcore +*/ + +/*! + \fn virtual HbDeviceDialogPluginInterface *HbDeviceDialogPluginInterface::createDeviceDialog( + const QString &deviceDialogType, const QVariantMap ¶meters) = 0 + + Creates a device dialog widget. The widget becomes visible immediately. Returns a pointer to + the device dialog widget interface or null if widget cannot be created. + + \param deviceDialogType Device dialog type to create. + \param parameters Device dialog parameters. The structure and meaning of parameters is a + contract between the plugin and a client. + + \sa HbDeviceDialogPlugin +*/ + +/*************************************************************************************************/ + +#include +#include +#ifdef Q_OS_SYMBIAN +#include +#endif // Q_OS_SYMBIAN + +// Constructor +HbDeviceDialogPlugin::HbDeviceDialogPlugin() +{ +#ifdef Q_OS_SYMBIAN + // Check loading process secure ID. Panic if not device dialog server. + const TUint32 sid = 0x20022FC5; + RProcess process; + if (process.SecureId().iId != sid) { + _LIT(KCategory, "HbDeviceDialogPlugin"); + User::Panic(KCategory, 1); + } +#endif // Q_OS_SYMBIAN +} + +// Destructor +HbDeviceDialogPlugin::~HbDeviceDialogPlugin() +{ +} + +HbDeviceDialogInterface::~HbDeviceDialogInterface() +{ +} + +QObject *HbDeviceDialogInterface::signalSender() const +{ + return 0; +}