--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/upnpavcontroller/upnpavcontrollerhelper/inc/upnpitemutility.h Thu Dec 17 08:52:00 2009 +0200
@@ -0,0 +1,207 @@
+/*
+* Copyright (c) 2007 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: Utility for parsing upnp items
+*
+*/
+
+
+
+
+
+
+#ifndef UPNPITEMUTILITY_H
+#define UPNPITEMUTILITY_H
+
+// INCLUDES
+#include <e32base.h>
+#include <upnpobject.h>
+#include <f32file.h>
+
+// FORWARD DECLARATIONS
+class CUpnpItem;
+class CUpnpObject;
+class CUpnpElement;
+class CUpnpAttribute;
+
+// CLASS DECLARATION
+
+/**
+* Utility for working with classes CUpnpObject and CUpnpItem.
+* The class provides helpers to locating elements and attributes
+* within the class, locating the resource and the URI, decoding
+* some special elements like dc:date, res@duration etc.
+*
+* @lib upnpavcontrollerhelper.lib
+* @since S60 3.2
+*/
+class UPnPItemUtility
+ {
+
+public: // Business logic methods
+
+ /**
+ * Tests if given object is of given class type.
+ * Note that in upnp the object classes are organised in open
+ * hierarchies, and this method will return true even if the class
+ * is unknown, if aObject's class is derived from aClass.
+ * see upnpconstantdefs.h for defined class definitions.
+ * example:
+ * TBool isPlaylist = BelongsToClass( item, KClassPlaylist );
+ *
+ * @since S60 3.2
+ * @param aObject the object whose class is to be tested
+ * @param aClass the class (in string form) against which to test
+ * @return reference to the res-element
+ */
+ IMPORT_C static TBool BelongsToClass(
+ const CUpnpObject& aObject,
+ const TDesC8& aClass );
+
+ /**
+ * Extracts all RES elements from an item.
+ * An item can include multiple resources, for instance
+ * an item may include the same image scaled to multiple
+ * resolutions, or a music track may include the track and
+ * its CR cover art as thumbnail.
+ * example:
+ * RUPnPElementsArray array;
+ * GetResElements( array );
+ *
+ * @since S60 3.2
+ * @param aItem UPnP item where to extract the res element.
+ * @return reference to the res-element
+ */
+ IMPORT_C static void GetResElements(
+ const CUpnpObject& aObject,
+ RUPnPElementsArray& aResElementsArray );
+
+ /**
+ * Finds the original resource of given item.
+ * Note that if item has multiple resource elements,
+ * this API will select the original and recommended one to use.
+ * Also note that if an item includes a thumbnail or another
+ * supporting resource, this can not be used to retrieve it.
+ * Example:
+ * const TDesC& uri = ResourceFromItemL( item ).Value();
+ *
+ * @since S60 3.2
+ * @param aItem UPnP item where to extract the res element.
+ * @return reference to the res-element
+ */
+ IMPORT_C static const CUpnpElement& ResourceFromItemL(
+ const CUpnpItem& aItem );
+
+ /**
+ * Finds an element within an object.
+ * see upnpconstantdefs.h for element name definitions.
+ * example:
+ * CUpnpElement* date = FindElementByName( item, KElementDate );
+ *
+ * @since S60 3.2
+ * @param aObject the object where to look for elements
+ * @param aName element name
+ * @return a pointer to the element, or NULL if not found
+ */
+ IMPORT_C static const CUpnpElement* FindElementByName(
+ const CUpnpObject& aObject, const TDesC8& aName );
+
+ /**
+ * Finds an element within an object.
+ * Leaves if not found.
+ * see upnpconstantdefs.h for element name definitions.
+ * example:
+ * TDesC& genre = FindElementByNameL( item, KElementDate ).Value();
+ *
+ * @since S60 3.2
+ * @param aObject the object where to look for elements
+ * @param aName element name
+ * @return a reference to the element found.
+ */
+ IMPORT_C static const CUpnpElement& FindElementByNameL(
+ const CUpnpObject& aObject, const TDesC8& aName );
+
+ /**
+ * Finds an attribute within an upnp element
+ * see upnpconstantdefs.h for element name definitions.
+ * example:
+ * CUpnpAttribute* s = FindAttributeByName( resElem, KAttributeSize );
+ *
+ * @since S60 3.2
+ * @param aElement the element where to look for attributes
+ * @param aName attribute name
+ * @return a pointer to the attribute found
+ */
+ IMPORT_C static const CUpnpAttribute* FindAttributeByName(
+ const CUpnpElement& aElement, const TDesC8& aName );
+
+ /**
+ * Finds an attribute within an upnp element.
+ * Leaves if not found
+ * see upnpconstantdefs.h for attribute name definitions.
+ * example:
+ * TDesC& s = FindAttributeByNameL( resElem, KAttributeSize ).Value();
+ *
+ * @since S60 3.2
+ * @param aElement the element where to look for attributes
+ * @param aName attribute name
+ * @return a reference to the attribute found
+ */
+ IMPORT_C static const CUpnpAttribute& FindAttributeByNameL(
+ const CUpnpElement& aElement, const TDesC8& aName );
+
+ /**
+ * Converts given upnp date string into TTime.
+ * example:
+ * TTime time = UpnpDateAsTTime( FindElementByNameL(
+ * item, KElementDate ).Value() );
+ *
+ * @since S60 3.2
+ * @param aUpnpDate value from item's dc:date element
+ * @param aTime out variable to receive corresponding TTime
+ * @return KErrNone if conversion was succesful, otherwise < 0
+ * for error values see TTime::Parse()
+ */
+ IMPORT_C static TInt UPnPDateAsTTime(
+ const TDesC8& aUpnpDate, TTime& aTime );
+
+ /**
+ * Converts given upnp duration or position string to a value in
+ * milliseconds.
+ * Duration was received in res element duration attribute, or
+ * in PositionInfo result from renderer.
+ * example:
+ * TInt duration = UpnpDurationAsMilliseconds( FindAttributeByNameL(
+ * ResourceFromItemL( item ), KAttributeDuration ).Value() );
+ *
+ * @since S60 3.2
+ * @param aDuration duration or position as string
+ * @param aMilliseconds out variable to receive the result
+ * @return KErrNone if conversion was succesful, otherwise < 0
+ */
+ IMPORT_C static TInt UPnPDurationAsMilliseconds(
+ const TDesC8& aDuration, TInt& aMilliseconds );
+
+private:
+
+ static void UPnPDateAsTTimeL( const TDesC8& aUpnpDate,
+ TTime& aTime );
+
+
+ };
+
+
+
+#endif // UPNPITEMUTILITY_H
+
+// End of File