Mercurial Mercurial > oss > FCL > sf > mw > hb / comparison
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/hbcore/devicedialogbase/hbdevicedialogsymbian.cpp
changeset 28 b7da29130b0e
parent 23 e6ad4ef83b23
child 30 80e4d18b72f5
equal deleted inserted replaced
23:e6ad4ef83b23 28:b7da29130b0e 
    34 #include "hbsymbianvariant.h"
 
    34 #include "hbsymbianvariant.h"
 
    35 #include "hbsymbianvariantconverter_p.h"
 
    35 #include "hbsymbianvariantconverter_p.h"
 
    36 #include "hbdeleteguardsymbian_p.h"
 
    36 #include "hbdeleteguardsymbian_p.h"
 
    37 
    37 
    38 /*!
 
    38 /*!
 
    39  \class CHbDeviceDialogSymbian
 
    39     \stable
 
    40  \brief CHbDeviceDialog displays dialogs on top of applications. It is a client interface for Symbian applications to Hb
 
    40     \hbcore
 
    41     device dialogs.
 
    41 
    42  \sa HbDeviceDialog
 
    42     \class CHbDeviceDialogSymbian
 
    43 
    43     \brief CHbDeviceDialogSymbian is a Symbian implementation of HbDeviceDialog. 
    44  Data given to this API in symbian format is packed to QVariantMap. See
 
    44 
    45  CHbSymbianVariant to see which Qt datatypes are supported.
 
    45     <b>This class is Symbian only. Not available on other platforms.</b>
 
    46  \sa CHbSymbianVariant
 
    46 
    47  \sa CHbSymbianVariantMap
 
    47     See HbDeviceDialog documentation to find out more about device dialogs.
 
    48 
    48 
    49  When plugin returns data in Qt format, the data is converted, if possible,
 
    49     CHbDeviceDialogSymbian is intended for use by Symbian servers that don't run Qt event loop
 
    50  to CHbSymbianVariantMap.
 
    50     and cannot use HbDeviceDialog.
 
    51 
    51 
    52  \stable
 
    52     The class is accompanied by classes CHbSymbianVariant and CHbSymbianVariantMap which
 
    53 
    53     are used to encapsulate device dialog parameters. Device dialog framework takes care of
 
    54  \hbcore
 
    54     translating Symbian data types to/from format understood by device dialog plugins.
 
       
    55 
       
    56     CHbDeviceDialogSymbian provides an asynchronous interface to show dialogs. Dialog closing
 
       
    57     and data events are indicated by MHbDeviceDialogObserver callback interface. 
       
    58 
       
    59     The code below launches a device dialog. Observer is not set and the dialog
 
       
    60     closes itself by timeout.
 
       
    61     \code
 
       
    62 
       
    63     CHbDeviceDialogSymbian* dialog = CHbDeviceDialogSymbian::NewL();
 
       
    64     CleanupStack::PushL(dialog);
 
       
    65     CHbSymbianVariantMap* map = CHbSymbianVariantMap::NewL();
 
       
    66     CleanupStack::PushL(map);
 
       
    67 
       
    68     _LIT(KTimeoutKey, "timeout");
 
       
    69     const TInt timeoutValue = 10000;
 
       
    70     CHbSymbianVariant* timeout = CHbSymbianVariant::NewL(&timeoutValue, CHbSymbianVariant::EInt);
 
       
    71     CleanupStack::PushL(timeout);
 
       
    72     User::LeaveIfError(map->Add(KTimeoutKey, timeout));
 
       
    73     CleanupStack::Pop(); // timeout
 
       
    74 
       
    75     _LIT(KTitleValue, "Sample title");
 
       
    76     _LIT(KTitleKey, "title");
 
       
    77     CHbSymbianVariant* title = CHbSymbianVariant::NewL(&KTitleValue(), CHbSymbianVariant::EDes);
 
       
    78     CleanupStack::PushL(title);
 
       
    79     User::LeaveIfError(map->Add(KTitleKey, title));
 
       
    80     CleanupStack::Pop(); // title
 
       
    81 
       
    82     _LIT(KTextValue, "Sample text");
 
       
    83     _LIT(KTextKey, "text");
 
       
    84     CHbSymbianVariant* text = CHbSymbianVariant::NewL(&KTextValue(), CHbSymbianVariant::EDes);
 
       
    85     CleanupStack::PushL(text);
 
       
    86     User::LeaveIfError(map->Add(KTextKey, text));
 
       
    87     CleanupStack::Pop(); // text
 
       
    88 
       
    89     _LIT(KDeviceDialogType, "com.nokia.hb.devicenotificationdialog/1.0");
 
       
    90     dialog->Show(KDeviceDialogType, *map);
 
       
    91     CleanupStack::PopAndDestroy(2); // dialog, map
 
       
    92     \endcode
 
       
    93 
       
    94     \sa HbDeviceDialog, CHbSymbianVariant, CHbSymbianVariantMap, MHbDeviceDialogObserver
 
    55  */
 
    95  */
 
    56 
    96 
    57 /*!
 
    97 /*!
 
    58     \enum CHbDeviceDialogSymbian::TDeviceDialogError
 
    98     \enum CHbDeviceDialogSymbian::TDeviceDialogError
 
    59     Defines device dialog error codes and ranges.
 
    99     Defines device dialog error codes and ranges.
 
    60 */
 
   100 */
 
    61 /*!
 
   101 /*!
 
    62     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::EFrameworkErrors
 
   102     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::EFrameworkErrors
 
    63     Start of an error range for errors originating from device dialog framework (client or server).
 
   103     Start of an error range for errors originating from device dialog framework (client or server).
 
    64 */
 
   104 */
 
    65 /*!
 
   105 /*!
 
    66     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::EPluginErrors
 
   106     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::EPluginErrors
 
    67     Start of an error range for errors originating from device dialog plugins. The framework passes
 
   107     Start of an error range for errors originating from device dialog plugins. The framework passes
 
    68     these from the plugin unmodified.
 
   108     these from the plugin unmodified.
 
    69 */
 
   109 */
 
    70 /*!
 
   110 /*!
 
    71     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::EErrorTypeMask
 
   111     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::EErrorTypeMask
 
    72     Mask for error type part of the error code.
 
   112     Mask for error type part of the error code.
 
    73 */
 
   113 */
 
    74 /*!
 
   114 /*!
 
    75     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::ECancelledError
 
   115     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::ECancelledError
 
    76     Operation was cancelled by Cancel().
 
   116     Operation was cancelled by Cancel().
 
    77 */
 
   117 */
 
    78 /*!
 
   118 /*!
 
    79     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::ESystemCancelledError
 
   119     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::ESystemCancelledError
 
    80     Operation was cancelled by device dialog framework.
 
   120     Operation was cancelled by device dialog framework.
 
    81 */
 
   121 */
 
    82 /*!
 
   122 /*!
 
    83     \var TDeviceDialogError::DeviceDialogError HbDeviceDialog::EInstanceExistsError
 
   123     \var CHbDeviceDialogSymbian::TDeviceDialogError CHbDeviceDialogSymbian::EInstanceExistsError
 
    84     A single instance device dialog widget exists already (has been launched).
 
   124     A single instance device dialog widget exists already (has been launched).
 
    85     See HbDeviceDialogPlugin::SingleInstance.
 
   125     See HbDeviceDialogPlugin::SingleInstance.
 
    86 */
 
   126 */
 
    87 
   127 
    88 /*!
 
   128 /*!
 
       
   129     \enum CHbDeviceDialogSymbian::TDeviceDialogFlag
 
       
   130     Defines construct flags.
 
       
   131 */
 
       
   132 /*!
 
       
   133     \var CHbDeviceDialogSymbian::TDeviceDialogFlag CHbDeviceDialogSymbian::ENoDeviceDialogFlags
 
       
   134     No flags specified.
 
       
   135 */
 
       
   136 /*!
 
       
   137     \var CHbDeviceDialogSymbian::TDeviceDialogFlag CHbDeviceDialogSymbian::EImmediateResourceReservation
 
       
   138     Reserves resources immediately instead of delaying until Show() is called.
 
       
   139 */
 
       
   140 /*!
 
       
   141     \var CHbDeviceDialogSymbian::TDeviceDialogFlag CHbDeviceDialogSymbian::EASyncServerStartup
 
       
   142     Starts device dialog service asynchronously.
 
       
   143 */
 
       
   144 
       
   145 /*!
 
    89    \fn void MHbDeviceDialogObserver::DataReceived(CHbSymbianVariantMap& aData)
 
   146    \fn void MHbDeviceDialogObserver::DataReceived(CHbSymbianVariantMap& aData)
 
    90 
   147 
    91     This callback is called when data is received from a device dialog.
 
   148     This callback is called when data is received from a device dialog.
 
    92     \a aData contains data from the dialog plugin.
 
   149     \a aData contains data from the dialog plugin. The structure and meaning
 
    93     The structure and meaning of the data is a contract between the dialog and
 
   150     of the data is a contract between the dialog and a client.
 
    94     a client. Structure should be aligned with the data types supported by
 
   151 
    95     CHbSymbianVariantMap.
 
   152     If no observer is set in CHbDeviceDialogSymbian::Show() the latest data
 
    96 
   153     can be retrieved with CHbDeviceDialogSymbian::receivedData().
 
    97     \sa CHbSymbianVariantMap.
 
   154 
       
   155     \sa CHbSymbianVariantMap
 
    98 */
 
   156 */
 
    99 
   157 
   100 /*!
 
   158 /*!
 
   101     \fn void MHbDeviceDialogObserver::DeviceDialogClosed(TInt aCompletionCode)
 
   159     \fn void MHbDeviceDialogObserver::DeviceDialogClosed(TInt aCompletionCode)
 
   102 
   160 
   103     This callback is called when a device dialog is closed. Any data sent by
 
   161     This callback is called when a device dialog is closed. Any data sent by
 
   104     the dialog is indicated by the dataReceived() callback. If no observer is
 
   162     the dialog is indicated by the dataReceived() callback.
 
   105     set in CHbDeviceDialogSymbian::Show the latest data can be retrieved with
 
       
   106     CHbDeviceDialogSymbian::receivedData()
 
       
   107 
   163 
   108     \a aCompletionCode gives the result of the dialog completion. Code can be
 
   164     \a aCompletionCode gives the result of the dialog completion. Code can be
 
   109     either Symbian error code or device dialog error code.
 
   165     either Symbian error code or device dialog error code.
 
   110 
   166 
   111     \sa DataReceived() ReceivedData()
 
   167     \sa DataReceived(), ReceivedData()
 
   112 */
 
   168 */
 
   113 
   169 
   114 // Device dialogs are implemented only for Symbian/S60 OS.
 
   170 NONSHARABLE_CLASS(CHbDeviceDialogSymbianPrivate) : public CActive
 
   115 
       
   116 class CHbDeviceDialogSymbianPrivate : public CActive
 
       
   117 {
 
   171 {
 
   118 public:
 
   172 public:
 
   119         CHbDeviceDialogSymbianPrivate(TInt aFlags);
 
   173         CHbDeviceDialogSymbianPrivate(TInt aFlags);
 
   120         ~CHbDeviceDialogSymbianPrivate();
 
   174         ~CHbDeviceDialogSymbianPrivate();
 
   121         TInt Initialize();
 
   175         TInt Initialize();
 
   236         SetError(error);
 
   290         SetError(error);
 
   237     }
 
   291     }
 
   238     return error;
 
   292     return error;
 
   239 }
 
   293 }
 
   240 
   294 
   241 /*!
 
   295 // Send device dialog update.
 
   242     \internal
 
       
   243 
       
   244     Send device dialog update.
 
       
   245 */
 
       
   246 TInt CHbDeviceDialogSymbianPrivate::Update( const QByteArray& aArray )
 
   296 TInt CHbDeviceDialogSymbianPrivate::Update( const QByteArray& aArray )
 
   247 {
 
   297 {
 
   248     TInt error = iLastError = KErrNone;
 
   298     TInt error = iLastError = KErrNone;
 
   249     if (iRequesting) {
 
   299     if (iRequesting) {
 
   250 
   300 
   261         SetError(error);
 
   311         SetError(error);
 
   262     }
 
   312     }
 
   263     return error;
 
   313     return error;
 
   264 }
 
   314 }
 
   265 
   315 
   266 /*!
 
   316 // Cancel a scheduled popup on HbDeviceDialogManager. Event buffer is cleared at server.
 
   267     \internal
 
       
   268 
       
   269     Cancel a scheduled popup on HbDeviceDialogManager. Event buffer is cleared
 
       
   270     at server.
 
       
   271 */
 
       
   272 void CHbDeviceDialogSymbianPrivate::CancelDialog()
 
   317 void CHbDeviceDialogSymbianPrivate::CancelDialog()
 
   273 {
 
   318 {
 
   274     iLastError = KErrNone;
 
   319     iLastError = KErrNone;
 
   275     int error = SymToDeviceDialogError(KErrNotFound);
 
   320     int error = SymToDeviceDialogError(KErrNotFound);
 
   276 
   321 
   282     if (error != KErrNone) {
 
   327     if (error != KErrNone) {
 
   283         SetError(error);
 
   328         SetError(error);
 
   284     }
 
   329     }
 
   285 }
 
   330 }
 
   286 
   331 
   287 /*!
 
   332 // Return last error.
 
   288     \internal
 
       
   289 
       
   290     Return last error.
 
       
   291 */
 
       
   292 TInt CHbDeviceDialogSymbianPrivate::Error() const
 
   333 TInt CHbDeviceDialogSymbianPrivate::Error() const
 
   293 {
 
   334 {
 
   294     return iLastError;
 
   335     return iLastError;
 
   295 }
 
   336 }
 
   296 
   337 
   297 void CHbDeviceDialogSymbianPrivate::SetObserver( MHbDeviceDialogObserver* aObserver )
 
   338 void CHbDeviceDialogSymbianPrivate::SetObserver( MHbDeviceDialogObserver* aObserver )
 
   298 {
 
   339 {
 
   299     iObserver = aObserver;
 
   340     iObserver = aObserver;
 
   300 }
 
   341 }
 
   301 /*!
 
   342 
   302     \internal
 
   343 // RunL from CActive.
 
   303     RunL from CActive.
 
       
   304 */
 
       
   305 void CHbDeviceDialogSymbianPrivate::RunL()
 
   344 void CHbDeviceDialogSymbianPrivate::RunL()
 
   306 {
 
   345 {
 
   307     TInt completionCode = iStatus.Int();
 
   346     TInt completionCode = iStatus.Int();
 
   308     int errorCode = SymToDeviceDialogError(completionCode);
 
   347     int errorCode = SymToDeviceDialogError(completionCode);
 
   309 
   348 
   388     if (iRequesting) {
 
   427     if (iRequesting) {
 
   389         Start();
 
   428         Start();
 
   390     }
 
   429     }
 
   391 }
 
   430 }
 
   392 
   431 
   393 /*!
 
   432 // DoCancel from CActive.
 
   394     \internal
 
       
   395     DoCancel from CActive.
 
       
   396 */
 
       
   397 void CHbDeviceDialogSymbianPrivate::DoCancel()
 
   433 void CHbDeviceDialogSymbianPrivate::DoCancel()
 
   398 {
 
   434 {
 
   399     SetError(KErrCancel);
 
   435     SetError(KErrCancel);
 
   400     iRequesting = EFalse;
 
   436     iRequesting = EFalse;
 
   401     iHbSession.SendSyncRequest(EHbSrvCancelUpdateChannel);
 
   437     iHbSession.SendSyncRequest(EHbSrvCancelUpdateChannel);
 
   402 }
 
   438 }
 
   403 
   439 
   404 /*!
 
   440 // RunError from CActive.
 
   405     \internal
 
       
   406     RunError from CActive.
 
       
   407 */
 
       
   408 TInt CHbDeviceDialogSymbianPrivate::RunError(TInt /*aError*/)
 
   441 TInt CHbDeviceDialogSymbianPrivate::RunError(TInt /*aError*/)
 
   409 {
 
   442 {
 
   410     SetError(SymToDeviceDialogError(KErrGeneral));
 
   443     SetError(SymToDeviceDialogError(KErrGeneral));
 
   411     return KErrNone;
 
   444     return KErrNone;
 
   412 }
 
   445 }
 
   413 
   446 
   414 /*!
 
   447 // Starts asynchronous message to receive update and close events from session.
 
   415     \internal
 
       
   416     Starts asynchronous message to receive update and close events from session.
 
       
   417 */
 
       
   418 void CHbDeviceDialogSymbianPrivate::Start()
 
   448 void CHbDeviceDialogSymbianPrivate::Start()
 
   419 {
 
   449 {
 
   420     iDataPtr.Zero();
 
   450     iDataPtr.Zero();
 
   421 
   451 
   422     if ( !IsActive() ) {
 
   452     if ( !IsActive() ) {
 
   493 {
 
   523 {
 
   494     delete d;
 
   524     delete d;
 
   495 }
 
   525 }
 
   496 
   526 
   497 /*!
 
   527 /*!
 
   498   Show of device dialog. Each time a Show() is called a new dialog is launched.
 
   528     Shows a device dialog. Each time a Show() is called, a new dialog is launched.
 
   499   aParameter data is sent to device dialog in Qt's QVariantMap object.
 
   529     The function is asynchronous and returns after the service has accepted the dialog.
 
   500   The function is asynchronous and returns immediately. Closing and data events from the
 
   530     Closing and data events from the dialog are indicated by observer interface.
 
   501   dialog can be received by observer interface. Deleting CHbDeviceDialogSymbian object
 
   531     Deleting CHbDeviceDialogSymbian object closes and deletes the device dialog at server
 
   502   closes and deletes the device dialog at server if observer is set. If observer is null
 
   532     if observer is set. If no observer is set, the dialog is left executing at the server
 
   503   the dialog is left executing at the server and it's assumed it closes itself by a timeout.
 
   533     and it's assumed it closes itself by a timeout. Cancel() closes the device dialog.
 
   504   Cancel() to closes the device dialog.
 
   534 
   505 
   535     \param aDeviceDialogType Identifies a device dialog.
 
   506   \a aDeviceDialogType is name of the device dialog. Identifies the device
 
   536     \param aParameters Contains parameters for the device dialog.
 
   507   dialog plugin. \a aParameters is a buffer containing data for the device dialog.
 
   537     \param aObserver Contains observer for the dialog or 0 for no observer.
 
   508 
   538 
   509   \a aObserver is used to observe the session.
 
   539     \return returns 0 on success or error code.
 
   510 
   540 
   511   Return value informs if the call was successful.
 
   541     \sa Update(), Cancel()
 
   512 
       
   513   \sa Update() Cancel()
 
       
   514  */
 
   542  */
 
   515 EXPORT_C TInt CHbDeviceDialogSymbian::Show(const TDesC& aDeviceDialogType, const CHbSymbianVariantMap& aParameters, MHbDeviceDialogObserver* aObserver)
 
   543 EXPORT_C TInt CHbDeviceDialogSymbian::Show(const TDesC& aDeviceDialogType, const CHbSymbianVariantMap& aParameters, MHbDeviceDialogObserver* aObserver)
 
   516 {
 
   544 {
 
   517     d->SetObserver(aObserver);
 
   545     d->SetObserver(aObserver);
 
   518 
   546 
   531     return d->Show(array);
 
   559     return d->Show(array);
 
   532 }
 
   560 }
 
   533 
   561 
   534 /*!
 
   562 /*!
 
   535     Updates device dialog parameters by a set of new values. Show() must be called before an
 
   563     Updates device dialog parameters by a set of new values. Show() must be called before an
 
   536     Update() can be called. Returns true on success and false
 
   564     Update() can be called.
 
   537     if error occurred.
 
   565 
       
   566     \param aParameters Contains parameters for the device dialog.
 
       
   567     
       
   568     \return returns 0 on success or error code.
 
   538 
   569 
   539     \sa Show()
 
   570     \sa Show()
 
   540 */
 
   571 */
 
   541 EXPORT_C TInt CHbDeviceDialogSymbian::Update(const CHbSymbianVariantMap& aParameters)
 
   572 EXPORT_C TInt CHbDeviceDialogSymbian::Update(const CHbSymbianVariantMap& aParameters)
 
   542 {
 
   573 {
 
   555 
   586 
   556     return d->Update(array);
 
   587     return d->Update(array);
 
   557 }
 
   588 }
 
   558 
   589 
   559 /*!
 
   590 /*!
 
   560     Get the data received from device dialog if using synchronous Show
 
   591     Gets the latest data received from a device dialog. If observer is set, data received from
 
   561     in s60 data types. Caller gets the ownership.
 
   592     device dialog is not saved and an empty container is returned.
 
       
   593 
       
   594     \return returns data received from device dialog. Ownership is transferred to caller.
 
   562 */
 
   595 */
 
   563 EXPORT_C CHbSymbianVariantMap* CHbDeviceDialogSymbian::ReceivedDataL() const
 
   596 EXPORT_C CHbSymbianVariantMap* CHbDeviceDialogSymbian::ReceivedDataL() const
 
   564 {
 
   597 {
 
   565     CHbSymbianVariantMap* map = HbSymbianVariantConverter::fromQVariantMapL(d->iDataReceived);
 
   598     CHbSymbianVariantMap* map = HbSymbianVariantConverter::fromQVariantMapL(d->iDataReceived);
 
   566     return map;
 
   599     return map;
 
   567 }
 
   600 }
 
   568 
   601 
   569 /*!
 
   602 /*!
 
   570     Cancel device dialog session. Visible dialog is removed from the screen.
 
   603     Cancels a device dialog. Visible dialog is closed and a queued one is deleted.
 
   571     Waiting dialogs are canceled and no effect if dialog already dismissed
 
   604     No effect if dialog has already closed.
 
   572 */
 
   605 */
 
   573 EXPORT_C void CHbDeviceDialogSymbian::Cancel()
 
   606 EXPORT_C void CHbDeviceDialogSymbian::Cancel()
 
   574 {
 
   607 {
 
   575     d->CancelDialog();
 
   608     d->CancelDialog();
 
   576 }
 
   609 }
 
   577 
   610 
   578 /*!
 
   611 /*!
 
   579     Set observer for device dialog events. \aObserver is pointer to the
 
   612     Sets observer for device dialog events.
 
   580     observer. Null disables observing.
 
   613 
       
   614     \param aObserver Contains observer for the device dialog. 0 disables observing.
 
   581 */
 
   615 */
 
   582 EXPORT_C void CHbDeviceDialogSymbian::SetObserver(MHbDeviceDialogObserver* aObserver)
 
   616 EXPORT_C void CHbDeviceDialogSymbian::SetObserver(MHbDeviceDialogObserver* aObserver)
 
   583 {
 
   617 {
 
   584     d->SetObserver(aObserver);
 
   618     d->SetObserver(aObserver);
 
   585 }
 
   619 }
FCL/sf/mw/hb