1 /** @file

     2 * Copyright (c) 2005-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:  Declares ElementFactory class.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_CUPNPELEMENTFACTORY_H

    20 #define C_CUPNPELEMENTFACTORY_H

    21 

    22 

    23 // INCLUDES

    24 

    25 #include <xmlengdom.h>

    26 #include <xmlengdocument.h>

    27 #include "upnpcontentdirectory.h"

    28 #include "upnpfiletransfer.h"

    29 #include "upnperrors.h" // Added by ClassView

    30 #include "upnpdominterface.h"

    31 

    32 // FORWARD DECLARATIONS

    33 

    34 class CUpnpElementFactory;

    35 class TUpnpContainerUpdateId;

    36 class CUpnpFileTransferTimerObserver;

    37 class CUpnpObject;

    38 class CUpnpItem;

    39 

    40 

    41 // FORWARD DECLARATIONS

    42 

    43 class CUpnpContentDirectory;

    44 

    45 // CLASS DECLARATION

    46 

    47 /**

    48 *  @brief Used to create content objects

    49 *

    50 *

    51 *  @lib contentdirectory.lib

    52 *  @since Series60 2.6

    53 */

    54 class CUpnpElementFactory : public CBase

    55 {

    56 public: // Constructors and destructors

    57                          

    58     /**

    59     * Gets active element from XML document. An active element

    60     * is a first element different from <DIDL-Lite> element.

    61     * @param aDocument XML document which will be search for active element.

    62     * @return handler to active element.

    63     */

    64     TXmlEngElement ActiveElementL( const RXmlEngDocument& aDocument );

    65     

    66     /**

    67     * Extracts active element from XML document. 

    68     * An active element is a first element different from <DIDL-Lite> element.

    69     * IMPORTANT: Caller takes responsibility for returned element. 

    70     * @param aDocument XML document which will be search for active element.

    71     * @return handler to extracted active element.

    72     */

    73     RXmlEngDocument ExtractActiveElementL( const RXmlEngDocument& aDocument );

    74     

    75     /**

    76     * Checks if two elements are equal and have exactly the same subtrees.

    77     * @param aFirst - first element to compare

    78     * @param aSecond - second element to compare

    79     * @return ETrue if elemants are equal.

    80     */

    81     TBool ElementsMatchL( TXmlEngElement aFirst, TXmlEngElement aSecond );

    82     

    83     /**

    84     * Counts elements in array that have the same name.

    85     * @param aName - name of elements, which will be counted.

    86     * @param aArray - array with elements to count.

    87     * @return number of found elements.

    88     */ 

    89     TInt CountElementsL( const TDesC8& aName, RArray<RXmlEngDocument>& aArray );

    90     

    91     /**

    92     * Counts elements in array that have the same name.

    93     * @param aName - name of elements, which will be counted.

    94     * @param aArray - array with elements to count.

    95     * @return number of found elements.

    96     */ 

    97     TInt CountElementsL( const TDesC8& aName, RArray<TXmlEngElement>& aArray );   

    98     

    99     /**

   100     * Gets classes descriptions for given object.

   101     * @param aObject - element representing object, which classes 

   102     *   descriptions we wan to acquire

   103     * @param aArray - (OUT) reference to array which will be filled with classes

   104     *   descriptions. 

   105     * @param aObjType - object type [item or container]

   106     */

   107     void ClassesL( const TXmlEngElement& aObject, RArray<TXmlEngElement>& aArray, const TDesC8& aObjType = KNullDesC8() );

   108     

   109     /**

   110     * Constructs descriptor with element's name and namespace prefix separated with colon.

   111     * IMPORTANT: As the function name indicates, it leaves pointer to heap descriptor on 

   112     * cleanup stack.

   113     * @param aElement - element for which descriptor will be constructed.

   114     * @return  - pointer to descriptor, allocated on the heap, containing element's name with prefix.

   115     */ 

   116     HBufC8* NameWithNsLC( const TXmlEngElement& aElement );

   117     

   118 

   119     /**

   120     * Two-phased constructor for building CUpnpElementFactory.

   121     * @since Series60 2.6

   122     */

   123     static CUpnpElementFactory* NewL( const TDesC& aObjectsXmlPath );

   124 

   125     /**

   126     * Two-phased constructor for building CUpnpElementFactory.

   127     * @since Series60 2.6

   128     */

   129     static CUpnpElementFactory* NewLC( const TDesC& aObjectsXmlPath );

   130 

   131     /**

   132     * Destructor function; called automatically from the destructor of a 

   133     * derived class

   134     */

   135     virtual ~CUpnpElementFactory();

   136 

   137     /**

   138     * Function to validate a new object given by Control Point, especially 

   139     * upnp:class element field eg. object.item.musictrack

   140     * IMPORTANT: If objects's description is invalid due to missing elements

   141     * it tries to repair it by adding those missing elements.

   142     * @since Series60 2.6

   143     * @param aElement element (xml) given by Control Point

   144     * @param aUpdateItem 

   145     * @return Returns a error code that is to be sent to caller of action.

   146     */

   147     TUpnpErrorCode ValidateNewObjectL( const TXmlEngElement& aNewElement, TBool aNew = ETrue, TBool aLocalSharing = EFalse );

   148     

   149     /**     

   150     * Function gets pointer to CUpnpContentDirectory and puts it into CUpnpElementFactory object 

   151     * @param aCD - pointer to CUpnpContentDirectory object

   152     */ 

   153     void GetContentDirectoryReference(CUpnpContentDirectory* aCD);

   154     

   155 private: // Constructors

   156 

   157     /**

   158     * C++ default constructor.

   159     */

   160     CUpnpElementFactory();

   161 

   162     /**

   163     * Second phase of the constructor.

   164     * By default Symbian 2nd phase constructor is private.

   165     * @param service Parent service

   166     */

   167     void ConstructL(const TDesC& aObjectsXmlPath);

   168 

   169 private: // New functions

   170     

   171     void ValidateBigImageL( TXmlEngElement aObj);

   172     

   173     /**

   174     *

   175     * @since Series S60 3.1

   176     * @param aPattern

   177     * @return boolean 

   178     */

   179     TBool IsRequiredL(TXmlEngElement aPattern);

   180     

   181     /**

   182     * Getter

   183     * @since Series S60 3.1

   184     * @param aPropertyName

   185     * @param aClassList

   186     * @return TXmlEngElement

   187     */

   188     TXmlEngElement GetPatternForResAttrL(const TDesC8& aPropertyName, RArray<TXmlEngElement>& aClassList );

   189     

   190     /**

   191     *

   192     * @since Series S60 3.1

   193     * @param aElement

   194     * @param aClassList

   195     */

   196     void ValidateResElL( TXmlEngElement aElement, RArray<TXmlEngElement>& aClassList);

   197     

   198     /**

   199     * Validates element

   200     * @since Series S60 3.1

   201     * @param aElement

   202     * @param aClasList

   203     */

   204     void ValidateElementL(TXmlEngElement aElement, RArray<TXmlEngElement>& aClassList);

   205     

   206     /**

   207     *

   208     * @since Series S60 3.1

   209     * @param aObj

   210     * @parma aClassList

   211     */

   212     void ValidatePropertiesL(TXmlEngElement aObj, RArray<TXmlEngElement>& aClassList);

   213     

   214     /**

   215     *

   216     * @since Series S60 3.1

   217     * @param aObj

   218     * @param aClassList

   219     */

   220     void ValidateMainAttributesL(TXmlEngElement aObj, RArray<TXmlEngElement>& aClassList);

   221     

   222     /**

   223     *

   224     * @since Series S60 3.1

   225     * @param aAttr

   226     * @parma aPattern

   227     */

   228     void ValidateElWithPatternL(TXmlEngElement aAttr, TXmlEngElement aPattern);

   229     

   230     /**

   231     *

   232     * @since Series S60 3.1

   233     * @param aAttr

   234     * @param aPattern

   235     */

   236     void ValidateAttrWithPatternL(TXmlEngAttr aAttr, TXmlEngElement aPattern);

   237     

   238     /**

   239     *

   240     * @since Series S60 3.1

   241     * @param aPropertyName

   242     * @param aClassList

   243     * @return TXmlEngElement

   244     */

   245     TXmlEngElement GetPatternL( const TDesC8& aPropertyName, RArray<TXmlEngElement>& aClassList, const TDesC8& aType );

   246     

   247     /**

   248     *

   249     * @since Series S60 3.1

   250     * @param aElement

   251     * @return boolean

   252     */

   253     TBool IsClassElement( const TXmlEngElement& aElement );

   254     

   255     /**

   256     *

   257     * @since Series S60 3.1

   258     * @param aElement

   259     * @return boolean

   260     */

   261     TBool IsNotEmptyImportUriL( const TXmlEngElement& aElement );

   262     

   263     /**

   264     *

   265     * @since Series S60 3.1

   266     * @param aElement

   267     * @return boolean

   268     */

   269     TBool IsMainObjectTagL(TXmlEngElement aElement);

   270 

   271     /**

   272     *

   273     * @since Series S60 3.1

   274     * @param aProtocolInfo

   275     * @param aLocalSharing

   276     * @return descriptor pointer

   277     */        

   278     HBufC8* ValidateProtocolInfoInResL( const TDesC8& aProtocolInfo, TBool aLocalSharing );

   279     

   280     /**

   281     *

   282     * @since Series S60 3.1

   283     * @param aElement    

   284     */

   285     void CheckDurationOfResElementL(const TXmlEngElement& aElement);

   286     

   287     /**

   288     *

   289     * @since Series S60 3.2

   290     * @param aElement    

   291     */

   292     void CheckSizeOfResElementL(const TXmlEngElement& aElement);

   293                     

   294 private: // Data

   295 

   296     // owned

   297     RXmlEngDocument               iDocument;

   298     // Pointer to content directory

   299     CUpnpContentDirectory*  iContentDirectory;

   300     RXmlEngDOMImplementation iDOMImpl;

   301 };

   302 

   303 #endif  // C_CUPNPELEMENTFACTORY_H

   304 

   305 // End of File