/*
* Copyright (c) 2005-2006 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:  Generic Active Idle Content item and Content item iterator definitions.
*
*/



#ifndef M_AICONTENTMODEL_H
#define M_AICONTENTMODEL_H

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

/**
 * Maximum length for a content item textual id.
 *
 * @see TAiContentItem::id
 */
const TInt KAiContentIdMaxLength = 255;

/**
 * Maximum length for content type.
 *
 * @see TAiContentItem::type
 */
const TInt KAiContentTypeMaxLength = 255;

/**
 * Null value for content id. Plug-in content model should never use this id
 * value in its content model.
 */
const TInt KAiNullContentId = KErrNotFound;

/**
 *  Encapsulates metadata of single plug-ins content item. The class is used
 *  as building block for the plug-ins content model, abstracts content
 *  selector, content reference and event.
 */
struct TAiContentItem
{
    /**
     * Plug-in specific id of this content item.
     */
    TInt id;

    /**
     * Textual id of this content item. Used for binding content items to
     * UI elements.
     *
     * @see KAiContentIdMaxLength
     */
    const wchar_t* cid;

    /**
     * Content item data MIME type. For example "text/plain" for textual 
     * content.
     *
     * @see KAiContentTypeMaxLength
     */
    const char* type;
};

/**
 * Helper function for accessing Content item textual id TAiContentItem::cid.
 *
 * This function's performance is relative to O(N) where N is the length of 
 * the textual id in characters. If the id of the same content item is accessed 
 * repeatedly (for example in a loop) store the returned id in a local TPtrC 
 * variable instead of calling this function repeatedly.
 *
 * @param aContentItem  content item whose textual id to return.
 * @return textual id of aContentItem as a descriptor.
 */
inline TPtrC16 ContentCid( const TAiContentItem& aContentItem )
    {
    return TPtrC16( (const TText16*) aContentItem.cid );
    }

/**
 * Helper function for accessing Content item data type TAiContentItem::type.
 *
 * This function's performance is relative to O(N) where N is the length of 
 * the type name in characters. If the type of the same content item is accessed 
 * repeatedly (for example in a loop) store the returned type in a local TPtrC8 
 * variable instead of calling this function repeatedly.
 *
 * @param aContentItem  content item whose type to return.
 * @return data type of aContentItem as a descriptor.
 */
inline TPtrC8 ContentType( const TAiContentItem& aContentItem )
    {
    return TPtrC8( (const TText8*) aContentItem.type );
    }


/**
 * Mime type for passing bitmap content data.
 * The content data should contain a packaged CGulIcon object pointer when this
 * MIME tyoe is used.
 *
 * @see CGulIcon
 * @see MAiContentObserver::PublishPtr
 */
const char KAiContentTypeBitmap[] = "image/x-s60-bitmap";

/**
 * MIME type for passing textual data.
 *
 * @see MAiContentObserver::Publish
 */
const char KAiContentTypeText[] = "text/plain";
 

/** MIME type for passing raw data.
 *
 * @see MAiContentObserver::PublishPtr
 */
const char KAiContentTypeData[] = "data/stream";
 
/**
 *  Abstract interface which provides services to iterate content items
 *  supported by the plug-in. Only used by the Active Idle Framework.
 *  Each plug-in must provide implementation of interface to access:
 *  content selectors, content references, and events. Instances of interface
 *  are accessed through method GetProperty in interface CAiContentPublisher.
 *
 *  @since S60 3.2
 */
class MAiContentItemIterator
{
public:
    /**
     * Tests if this enumeration contains more elements.
     *
     * @return ETrue if this iterator object contains at least one more
     *         element to provide; EFalse otherwise.
     */
    virtual TBool HasNext() const = 0;

    /**
     * Returns the next element of this iterator if this enumeration object
     * has at least one more element to provide.
     *
     * @return The next element.
     * @leave KErrOverflow if iterator is at the end of range.
     */
    virtual const TAiContentItem& NextL() = 0;

    /**
     * Returns the first element of this iterator which matches aId.
     *
     * @param  aId - unique identification of the content item, corresponds
     *         to TAiContentItem::id.
     * @return The first element matching aId.
     * @leave KErrNotFound if element matching aId is not found from the
     *            complete iterator range.
     */
    virtual const TAiContentItem& ItemL( TInt aId ) const = 0;

    /**
     * Returns the first element of this iterator which matches aCid.
     *
     * @param  aCid - textual identification of the content item, corresponds
     *         to TAiContentItem::cid.
     * @return The first element matching aCid.
     * @leave KErrNotFound if element matching aCid is not found from the
     *            complete iterator range.
     */
    virtual const TAiContentItem& ItemL( const TDesC& aCid ) const = 0;

    /**
     * Resets iterator to the first item in the list.
     */
    virtual void Reset() = 0;

    /**
     * Release the iterator.
     */
    virtual void Release() = 0;
    
protected:
    /**
     * Protected destructor prevents deletion through this interface.
     */
    ~MAiContentItemIterator() { }

private:
    /**
     * Required to implement CleanupReleasePushL(MAiContentItemIterator*).
     */
    static void Cleanup(TAny* aSelf);
    friend void CleanupReleasePushL(MAiContentItemIterator*);
};

/**
 * Helper function which calls MAiContentItemIterator::Release() with NULL 
 * checking. Especially useful in destructors.
 */
inline void Release(MAiContentItemIterator* aObj)
    {
    if (aObj) aObj->Release();
    }

/**
 * 
 */
inline void CleanupReleasePushL(MAiContentItemIterator* aObj)
    {
    CleanupStack::PushL(
        TCleanupItem(&MAiContentItemIterator::Cleanup, aObj) );
    }

/**
 * Required to implement CleanupReleasePushL(MAiContentItemIterator*).
 * Inline to avoid problems with multiple definitions.
 */
inline void MAiContentItemIterator::Cleanup(TAny* aSelf)
    {
    ::Release(static_cast<MAiContentItemIterator*>(aSelf));
    }



#endif // M_AICONTENTMODEL_H