1 /*

     2 * Copyright (c) 2007 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:      Utility for parsing upnp items

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 #ifndef UPNPITEMUTILITY_H

    24 #define UPNPITEMUTILITY_H

    25 

    26 //  INCLUDES

    27 #include <e32base.h>

    28 #include <upnpobject.h>

    29 #include <f32file.h>

    30 

    31 // FORWARD DECLARATIONS

    32 class CUpnpItem;

    33 class CUpnpObject;

    34 class CUpnpElement;

    35 class CUpnpAttribute;

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

    40 * Utility for working with classes CUpnpObject and CUpnpItem.

    41 * The class provides helpers to locating elements and attributes

    42 * within the class, locating the resource and the URI, decoding

    43 * some special elements like dc:date, res@duration etc.

    44 *

    45 * @lib upnpavcontrollerhelper.lib

    46 * @since S60 3.2

    47 */

    48 class UPnPItemUtility

    49     {

    50 

    51 public: // Business logic methods

    52 

    53     /**

    54      * Tests if given object is of given class type.

    55      * Note that in upnp the object classes are organised in open

    56      * hierarchies, and this method will return true even if the class

    57      * is unknown, if aObject's class is derived from aClass.

    58      * see upnpconstantdefs.h for defined class definitions.

    59      * example:

    60      * TBool isPlaylist = BelongsToClass( item, KClassPlaylist );

    61      *

    62      * @since S60 3.2

    63      * @param aObject the object whose class is to be tested

    64      * @param aClass the class (in string form) against which to test

    65      * @return reference to the res-element

    66      */

    67     IMPORT_C static TBool BelongsToClass(

    68         const CUpnpObject& aObject,

    69         const TDesC8& aClass );

    70 

    71     /**

    72      * Extracts all RES elements from an item.

    73      * An item can include multiple resources, for instance

    74      * an item may include the same image scaled to multiple

    75      * resolutions, or a music track may include the track and

    76      * its CR cover art as thumbnail.

    77      * example:

    78      * RUPnPElementsArray array;

    79      * GetResElements( array );

    80      *

    81      * @since S60 3.2

    82      * @param aItem UPnP item where to extract the res element.

    83      * @return reference to the res-element

    84      */

    85     IMPORT_C static void GetResElements(

    86         const CUpnpObject& aObject,

    87         RUPnPElementsArray& aResElementsArray );

    88 

    89     /**

    90      * Finds the original resource of given item.

    91      * Note that if item has multiple resource elements,

    92      * this API will select the original and recommended one to use.

    93      * Also note that if an item includes a thumbnail or another

    94      * supporting resource, this can not be used to retrieve it.

    95      * Example:

    96      * const TDesC& uri = ResourceFromItemL( item ).Value();

    97      *

    98      * @since S60 3.2

    99      * @param aItem UPnP item where to extract the res element.

   100      * @return reference to the res-element

   101      */

   102     IMPORT_C static const CUpnpElement& ResourceFromItemL(

   103         const CUpnpItem& aItem );

   104 

   105     /**

   106      * Finds an element within an object.

   107      * see upnpconstantdefs.h for element name definitions.

   108      * example:

   109      * CUpnpElement* date = FindElementByName( item, KElementDate );

   110      *

   111      * @since S60 3.2

   112      * @param aObject the object where to look for elements

   113      * @param aName element name

   114      * @return a pointer to the element, or NULL if not found

   115      */

   116     IMPORT_C static  const CUpnpElement* FindElementByName(

   117         const CUpnpObject& aObject, const TDesC8& aName );

   118 

   119     /**

   120      * Finds an element within an object.

   121      * Leaves if not found.

   122      * see upnpconstantdefs.h for element name definitions.

   123      * example:

   124      * TDesC& genre = FindElementByNameL( item, KElementDate ).Value();

   125      *

   126      * @since S60 3.2

   127      * @param aObject the object where to look for elements

   128      * @param aName element name

   129      * @return a reference to the element found.

   130      */

   131     IMPORT_C static  const CUpnpElement& FindElementByNameL(

   132         const CUpnpObject& aObject, const TDesC8& aName );

   133 

   134     /**

   135      * Finds an attribute within an upnp element

   136      * see upnpconstantdefs.h for element name definitions.

   137      * example:

   138      * CUpnpAttribute* s = FindAttributeByName( resElem, KAttributeSize );

   139      *

   140      * @since S60 3.2

   141      * @param aElement the element where to look for attributes

   142      * @param aName attribute name

   143      * @return a pointer to the attribute found

   144      */

   145     IMPORT_C static const CUpnpAttribute* FindAttributeByName(

   146         const CUpnpElement& aElement, const TDesC8& aName );

   147 

   148     /**

   149      * Finds an attribute within an upnp element.

   150      * Leaves if not found

   151      * see upnpconstantdefs.h for attribute name definitions.

   152      * example:

   153      * TDesC& s = FindAttributeByNameL( resElem, KAttributeSize ).Value();

   154      *

   155      * @since S60 3.2

   156      * @param aElement the element where to look for attributes

   157      * @param aName attribute name

   158      * @return a reference to the attribute found

   159      */

   160     IMPORT_C static const CUpnpAttribute& FindAttributeByNameL(

   161         const CUpnpElement& aElement, const TDesC8& aName );

   162 

   163     /**

   164      * Converts given upnp date string into TTime.

   165      * example:

   166      * TTime time = UpnpDateAsTTime( FindElementByNameL(

   167      *      item, KElementDate ).Value() );

   168      *

   169      * @since S60 3.2

   170      * @param aUpnpDate value from item's dc:date element

   171      * @param aTime out variable to receive corresponding TTime

   172      * @return KErrNone if conversion was succesful, otherwise < 0

   173      *         for error values see TTime::Parse()

   174      */

   175     IMPORT_C static TInt UPnPDateAsTTime(

   176         const TDesC8& aUpnpDate, TTime& aTime );

   177 

   178     /**

   179      * Converts given upnp duration or position string to a value in

   180      * milliseconds.

   181      * Duration was received in res element duration attribute, or

   182      * in PositionInfo result from renderer.

   183      * example:

   184      * TInt duration = UpnpDurationAsMilliseconds( FindAttributeByNameL(

   185      *      ResourceFromItemL( item ), KAttributeDuration ).Value() );

   186      *

   187      * @since S60 3.2

   188      * @param aDuration duration or position as string

   189      * @param aMilliseconds out variable to receive the result

   190      * @return KErrNone if conversion was succesful, otherwise < 0

   191      */

   192     IMPORT_C static TInt UPnPDurationAsMilliseconds(

   193         const TDesC8& aDuration, TInt& aMilliseconds );

   194 

   195 private:

   196 

   197     static void UPnPDateAsTTimeL( const TDesC8& aUpnpDate,

   198         TTime& aTime );

   199 

   200 

   201     };

   202 

   203 

   204 

   205 #endif  // UPNPITEMUTILITY_H

   206 

   207 // End of File