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:  Context publishing helper dll

    15  *

    16 */

    17 

    18 

    19 #ifndef HGCONTEXTUTILITY_H

    20 #define HGCONTEXTUTILITY_H

    21 

    22 #include <e32base.h>

    23 #include <e32cmn.h>

    24 #include <bamdesca.h>

    25 #include <badesca.h>

    26 #include <mdccommon.h>

    27 #include <hg/hgcontextutilitybase.h>

    28 

    29 class MVPbkStoreContact;

    30 class MVPbkContactLink;

    31 class CVPbkContactLinkArray;

    32 class CMdESession;

    33 

    34 /**

    35  *  Utility class to publish and access context through the Context Framework.

    36  *  @lib hgcontextutility.lib

    37  *

    38  *  Typical usage in applications that are publishing context:

    39  *  During construction:

    40  *  \code

    41  *    iContextUtility = CHgContextUtility::NewL();

    42  *    iContextUtility->RePublishWhenFgL( ETrue );

    43  *  \endcode

    44  *  Publishing is accomplished with one single call, for example:

    45  *  \code

    46  *    void ContactChanged( MVPbkStoreContact* aNewContact ) {

    47  *      ...

    48  *      iContextUtility->PublishContactContextL( *aNewContact );

    49  *      ...

    50  *  \endcode

    51  *

    52  *  By default publishing requests are ignored if the application is

    53  *  not in foreground (does not apply to apps that do not have the

    54  *  ui environment). If there is still a good reason to allow this

    55  *  then call AllowPublishFromBackground( ETrue ).

    56  */

    57 NONSHARABLE_CLASS( CHgContextUtility ) : public CHgContextUtilityBase

    58     {

    59 public:

    60     /**

    61      * 2-phased constructor.

    62      */

    63     IMPORT_C static CHgContextUtility* NewL();

    64     

    65     /**

    66      * 2-phased constructor.

    67      */

    68     IMPORT_C static CHgContextUtility* NewLC();

    69     

    70     /*

    71      * Destructor.

    72      */

    73     IMPORT_C ~CHgContextUtility();

    74 

    75     /**

    76      * Publishes contact context.

    77      * @param   aContact            contact

    78      * @param   aDelay              if non-zero then context is published only after

    79      * a short delay. If a new publish call is made before the timer fires the

    80      * pending value will not be published.

    81      */

    82     IMPORT_C void PublishContactContextL( const MVPbkStoreContact& aContact,

    83         const TTimeIntervalMicroSeconds32& aDelay = 0 );

    84 

    85     /**

    86      * Publishes contact context.

    87      * @param   aContactLink        contact link

    88      * @param   aDelay              if non-zero then context is published only after

    89      * a short delay. If a new publish call is made before the timer fires the

    90      * pending value will not be published.

    91      */

    92     IMPORT_C void PublishContactContextL( const MVPbkContactLink& aContactLink,

    93         const TTimeIntervalMicroSeconds32& aDelay = 0 );

    94 

    95     /**

    96      * Publishes contact context.

    97      * Attempts to publish an empty value will be ignored.

    98      *

    99      * Prefer using the overloads taking vpbk contact or link, whenever possible.

   100      * Use this in case of unknown contacts only, that is, a name, phone number,

   101      * or email address that does not belong to a phonebook contact.

   102      *

   103      * @param   aContactName    formatted name, phone number, or email address,

   104      * or a combination of them, e.g. "firstname lastname", "+12345678",

   105      * "lastname firstname <abcd@efg.com>", "firstname, lastname <0501234567>".

   106      * @param   aDelay              if non-zero then context is published only after

   107      * a short delay. If a new publish call is made before the timer fires the

   108      * pending value will not be published.

   109      */

   110     IMPORT_C void PublishContactContextL( const TDesC& aContactName,

   111         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   112 

   113     /**

   114      * Overload for publishing multiple contacts.

   115      * Ownership of passed pointers is not taken.

   116      * @param   aContacts           contact array

   117      * @param   aDelay              if non-zero then context is published only after

   118      * a short delay. If a new publish call is made before the timer fires the

   119      * pending value will not be published.

   120      */

   121     IMPORT_C void PublishContactContextL(

   122         const RPointerArray<MVPbkStoreContact>& aContacts,

   123         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   124 

   125     /**

   126      * Overload for publishing multiple contacts.

   127      * @param   aContactLinks       contact link array

   128      * @param   aDelay              if non-zero then context is published only after

   129      * a short delay. If a new publish call is made before the timer fires the

   130      * pending value will not be published.

   131      */

   132     IMPORT_C void PublishContactContextL(

   133         const CVPbkContactLinkArray& aContactLinks,

   134         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   135 

   136     /**

   137      * Overload for publishing multiple contacts.

   138      * @param   aContactNames   string array, for element format

   139      * see PublishContactContextL(const TDesC&)

   140      * @param   aDelay              if non-zero then context is published only after

   141      * a short delay. If a new publish call is made before the timer fires the

   142      * pending value will not be published.

   143      */

   144     IMPORT_C void PublishContactContextL( const MDesCArray& aContactNames,

   145         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   146 

   147     /**

   148      * Publishes freetext context.

   149      * Not to be used for bulk text (e.g. full content of some text viewer component).

   150      * @param   aText   some text, typically the highlighted substring

   151      * from a viewer or editor control

   152      * @param   aDelay              if non-zero then context is published only after

   153      * a short delay. If a new publish call is made before the timer fires the

   154      * pending value will not be published.

   155      */

   156     IMPORT_C void PublishTextContextL( const TDesC& aText,

   157         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   158 

   159     /**

   160      * Publishes URL context.

   161      * @param   aUrl    URL

   162      * @param   aDelay              if non-zero then context is published only after

   163      * a short delay. If a new publish call is made before the timer fires the

   164      * pending value will not be published.

   165      */

   166     IMPORT_C void PublishUrlContextL( const TDesC& aUrl,

   167         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   168 

   169     /**

   170      * Publishes date/time context.

   171      * @param   aTime   time

   172      * @param   aDelay              if non-zero then context is published only after

   173      * a short delay. If a new publish call is made before the timer fires the

   174      * pending value will not be published.

   175      */

   176     IMPORT_C void PublishTimeContextL( const TTime& aTime,

   177         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   178 

   179     /**

   180      * Publishes photo context.

   181      * @param   aFilename   name of image file, with full path

   182      * @param   aDelay              if non-zero then context is published only after

   183      * a short delay. If a new publish call is made before the timer fires the

   184      * pending value will not be published.

   185      */

   186     IMPORT_C void PublishPhotoContextL( const TDesC& aFilename,

   187         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   188 

   189     /**

   190      * Publishes photo context.

   191      * @param   aMdeItemId  item id for the Image object in MDS

   192      * @param   aMdeSession opened metadata engine session

   193      * @param   aDelay              if non-zero then context is published only after

   194      * a short delay. If a new publish call is made before the timer fires the

   195      * pending value will not be published.

   196      */

   197     IMPORT_C void PublishPhotoContextL( TItemId aMdeItemId,

   198         CMdESession& aMdeSession,

   199         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   200     

   201     /**

   202      * Publishes TV context.

   203      * Pass KNullDesC if some of the needed data is not available.

   204      * @param   aChannelName        channel name

   205      * @param   aProgramName        program name

   206      * @param   aProgramDescription program description

   207      * @param   aGenre              genre

   208      */

   209     IMPORT_C void PublishTvContextL(

   210         const TDesC& aChannelName,

   211         const TDesC& aProgramName,

   212         const TDesC& aProgramDescription,

   213         const TDesC& aGenre );

   214 

   215     /**

   216      * Publishes an account id as contact context.

   217      *

   218      * @param   aServiceId  the service prefix, e.g. "Ovi"

   219      * @param   aAccountId  the account id

   220      * @param   aDelay   if non-zero then context is published only after

   221      * a short delay. If a new publish call is made before the timer fires the

   222      * pending value will not be published.

   223      */

   224     IMPORT_C void PublishServiceIdL( const TDesC& aServiceId,

   225         const TDesC& aAccountId,

   226         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   227 

   228     /**

   229      * Enables or disables automatic re-publishing of the latest

   230      * context (published via this context utility instance) whenever

   231      * the application comes to foreground.

   232      *

   233      * It is DISABLED by default.

   234      *

   235      * By enabling this the applications do not have to care about

   236      * context publishing in HandleForegroundEventL etc.

   237      *

   238      * The feature needs CCoeEnv and calls will be ignored if the

   239      * environment is not available.

   240      *

   241      * @param   aEnable     flag to turn the feature on/off

   242      */

   243     IMPORT_C void RePublishWhenFgL( TBool aEnable );

   244 

   245     /**

   246      * Enables or disables context publishing when being in background.

   247      * Applies to all PublishContextL variants.

   248      * If disabled then no context will be published if it seems that the

   249      * caller application is not in foreground.

   250      * Has no effect if there is no CCoeEnv available, publishing is always

   251      * allowed in that case.

   252      *

   253      * It is DISABLED by default, that is, publishing is not allowed

   254      * from applications that are not in foreground.

   255      *

   256      * @param   aAllow  flag to turn the feature on/off

   257      */

   258     IMPORT_C void AllowPublishFromBackground( TBool aAllow );

   259         

   260     /**

   261      * Adds new music context info to music context publishing parameters.

   262      * This method is to be used in context with PublishMusicContextL. Fill in the

   263      * parameters and then call PublishMusicContextL.

   264      * This parameter list is cleared after publishing music context.

   265      * 

   266      * @param aKey Name of the key to be published.

   267      * @param aData Data for the key.

   268      * @leave KErrNotFound, when key is empty.

   269      * @leave KErrAlreadyExists, when key is already in the list.

   270      * @see hgcontextdef.h for keys

   271      * @see PublishMusicContextL

   272      */

   273     IMPORT_C void AddMusicContextInfoL( const TDesC& aKey, const TDesC& aData );

   274     

   275     /**

   276      * Publishes music context from provided parameters as music context.

   277      * Publishes all known (in hgcontextdef.h) music context fields as music

   278      * context. All keys, which do not contain any data, are automatically 

   279      * filled with '<unknown>' -string.

   280      * Clears the parameter list after publishing the context.

   281      * 

   282      * @leave KErrNotReady, when music context data parameter list is empty.

   283      * * @see hgcontextdef.h for keys

   284      * @see AddMusicContextInfoL

   285      */

   286     IMPORT_C void PublishMusicContextL( 

   287         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   288     

   289     /**

   290      * Publishes Radio context.

   291      * Pass KNullDesC if some of the needed data is not available.

   292      * @param   aRadioName        radio name

   293      * @param   aRadioUrl         radio url

   294      * @param   aRadioFrequency   radio frequency

   295      * @param   aRadioRDSPI       radio identification code

   296      */

   297     IMPORT_C void PublishRadioContextL( 

   298             const TDesC& aRadioName,

   299             const TDesC& aRadioUrl,

   300             const TDesC& aRadioFrequency,

   301             const TDesC& aRadioRDSPI );

   302     

   303     /**

   304      * Creates a combined string from the elements of the given array.

   305      * Returns NULL if the array has less than 2 elements.

   306      * @param   aArray      string array

   307      * @return  combined string or NULL, ownership transferred to caller

   308      */

   309     IMPORT_C static HBufC* BuildCombinedStringL( const MDesCArray& aArray );

   310 

   311     /**

   312      * Splits the given combined string and appends the components to

   313      * the given array. The initial content of the array is not modified.

   314      * If aString does not seem to be a string combined from multiple entries

   315      * then aString is appended to aArray without any changes.

   316      * @param   aString     combined string, input

   317      * @param   aArray      array, output

   318      */

   319     IMPORT_C static void SplitCombinedStringL( const TDesC& aString,

   320         CDesCArray& aArray );

   321 

   322 protected:

   323     CHgContextUtility();

   324     void ConstructL();

   325     };

   326     

   327 #endif /* HGCONTEXTUTILITY_H */