1 /*

     2 * Copyright (c) 2006-2006 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:  

    15 *

    16 */

    17 

    18 

    19 #ifndef M_AICONTENTMODEL_H

    20 #define M_AICONTENTMODEL_H

    21 

    22 #include <e32base.h>

    23 #include <libc/stddef.h>  // For wchar_t

    24 

    25 /**

    26  * Maximum length for a content item textual id.

    27  *

    28  * @see TAiContentItem::id

    29  */

    30 const TInt KAiContentIdMaxLength = 255;

    31 

    32 /**

    33  * Maximum length for content type.

    34  *

    35  * @see TAiContentItem::type

    36  */

    37 const TInt KAiContentTypeMaxLength = 255;

    38 

    39 /**

    40  * Null value for content id. Plug-in content model should never use this id

    41  * value in its content model.

    42  */

    43 const TInt KAiNullContentId = KErrNotFound;

    44 

    45 /**

    46  *  Encapsulates metadata of single plug-ins content item. The class is used

    47  *  as building block for the plug-ins content model, abstracts content

    48  *  selector, content reference and event.

    49  */

    50 struct TAiContentItem

    51 {

    52     /**

    53      * Plug-in specific id of this content item.

    54      */

    55     TInt id;

    56 

    57     /**

    58      * Textual id of this content item. Used for binding content items to

    59      * UI elements.

    60      *

    61      * @see KAiContentIdMaxLength

    62      */

    63     const wchar_t* cid;

    64 

    65     /**

    66      * Content item data MIME type. For example "text/plain" for textual 

    67      * content.

    68      *

    69      * @see KAiContentTypeMaxLength

    70      */

    71     const char* type;

    72 };

    73 

    74 /**

    75  * Helper function for accessing Content item textual id TAiContentItem::cid.

    76  *

    77  * This function's performance is relative to O(N) where N is the length of 

    78  * the textual id in characters. If the id of the same content item is accessed 

    79  * repeatedly (for example in a loop) store the returned id in a local TPtrC 

    80  * variable instead of calling this function repeatedly.

    81  *

    82  * @param aContentItem  content item whose textual id to return.

    83  * @return textual id of aContentItem as a descriptor.

    84  */

    85 inline TPtrC16 ContentCid( const TAiContentItem& aContentItem )

    86     {

    87     return TPtrC16( (const TText16*) aContentItem.cid );

    88     }

    89 

    90 /**

    91  * Helper function for accessing Content item data type TAiContentItem::type.

    92  *

    93  * This function's performance is relative to O(N) where N is the length of 

    94  * the type name in characters. If the type of the same content item is accessed 

    95  * repeatedly (for example in a loop) store the returned type in a local TPtrC8 

    96  * variable instead of calling this function repeatedly.

    97  *

    98  * @param aContentItem  content item whose type to return.

    99  * @return data type of aContentItem as a descriptor.

   100  */

   101 inline TPtrC8 ContentType( const TAiContentItem& aContentItem )

   102     {

   103     return TPtrC8( (const TText8*) aContentItem.type );

   104     }

   105 

   106 

   107 /**

   108  * Mime type for passing bitmap content data.

   109  * The content data should contain a packaged CGulIcon object pointer when this

   110  * MIME tyoe is used.

   111  *

   112  * @see CGulIcon

   113  * @see MAiContentObserver::PublishPtr

   114  */

   115 const char KAiContentTypeBitmap[] = "image/x-s60-bitmap";

   116 

   117 /**

   118  * MIME type for passing textual data.

   119  *

   120  * @see MAiContentObserver::Publish

   121  */

   122 const char KAiContentTypeText[] = "text/plain";

   123  

   124 

   125 /**

   126  *  Abstract interface which provides services to iterate content items

   127  *  supported by the plug-in. Only used by the Active Idle Framework.

   128  *  Each plug-in must provide implementation of interface to access:

   129  *  content selectors, content references, and events. Instances of interface

   130  *  are accessed through method GetProperty in interface CAiContentPublisher.

   131  *

   132  *  @since S60 3.2

   133  */

   134 class MAiContentItemIterator

   135 {

   136 public:

   137     /**

   138      * Tests if this enumeration contains more elements.

   139      *

   140      * @return ETrue if this iterator object contains at least one more

   141      *         element to provide; EFalse otherwise.

   142      */

   143     virtual TBool HasNext() const = 0;

   144 

   145     /**

   146      * Returns the next element of this iterator if this enumeration object

   147      * has at least one more element to provide.

   148      *

   149      * @return The next element.

   150      * @leave KErrOverflow if iterator is at the end of range.

   151      */

   152     virtual const TAiContentItem& NextL() = 0;

   153 

   154     /**

   155      * Returns the first element of this iterator which matches aId.

   156      *

   157      * @param  aId - unique identification of the content item, corresponds

   158      *         to TAiContentItem::id.

   159      * @return The first element matching aId.

   160      * @leave KErrNotFound if element matching aId is not found from the

   161      *            complete iterator range.

   162      */

   163     virtual const TAiContentItem& ItemL( TInt aId ) const = 0;

   164 

   165     /**

   166      * Returns the first element of this iterator which matches aCid.

   167      *

   168      * @param  aCid - textual identification of the content item, corresponds

   169      *         to TAiContentItem::cid.

   170      * @return The first element matching aCid.

   171      * @leave KErrNotFound if element matching aCid is not found from the

   172      *            complete iterator range.

   173      */

   174     virtual const TAiContentItem& ItemL( const TDesC& aCid ) const = 0;

   175 

   176     /**

   177      * Resets iterator to the first item in the list.

   178      */

   179     virtual void Reset() = 0;

   180 

   181     /**

   182      * Release the iterator.

   183      */

   184     virtual void Release() = 0;

   185     

   186 protected:

   187     /**

   188      * Protected destructor prevents deletion through this interface.

   189      */

   190     ~MAiContentItemIterator() { }

   191 

   192 private:

   193     /**

   194      * Required to implement CleanupReleasePushL(MAiContentItemIterator*).

   195      */

   196     static void Cleanup(TAny* aSelf);

   197     friend void CleanupReleasePushL(MAiContentItemIterator*);

   198 };

   199 

   200 /**

   201  * Helper function which calls MAiContentItemIterator::Release() with NULL 

   202  * checking. Especially useful in destructors.

   203  */

   204 inline void Release(MAiContentItemIterator* aObj)

   205     {

   206     if (aObj) aObj->Release();

   207     }

   208 

   209 /**

   210  * 

   211  */

   212 inline void CleanupReleasePushL(MAiContentItemIterator* aObj)

   213     {

   214     CleanupStack::PushL(

   215         TCleanupItem(&MAiContentItemIterator::Cleanup, aObj) );

   216     }

   217 

   218 /**

   219  * Required to implement CleanupReleasePushL(MAiContentItemIterator*).

   220  * Inline to avoid problems with multiple definitions.

   221  */

   222 inline void MAiContentItemIterator::Cleanup(TAny* aSelf)

   223     {

   224     ::Release(static_cast<MAiContentItemIterator*>(aSelf));

   225     }

   226 

   227 

   228 

   229 #endif // M_AICONTENTMODEL_H