1 /** @file

     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:  Declares the CUpnpContentHandlersController class

    15  *

    16 */

    17 

    18 

    19 #ifndef __UPNPCONTENTHANDLERSCONTROLLER_H__

    20 #define __UPNPCONTENTHANDLERSCONTROLLER_H__

    21 

    22 #include <xml/parser.h>

    23 #include <xml/contenthandler.h>

    24 #include <cstack.h>

    25 #include "upnpsoapparser.h"

    26 

    27 // CLASS DECLARATION

    28 class CUpnpDevice;

    29 class CUpnpDeviceImplementation;

    30 class CUpnpSilentDeviceImplementation;

    31 class CUpnpService;

    32 class CUpnpContentHandler;

    33 class CUpnpDescriptionProperty;

    34 class CUpnpAction;

    35 class CUpnpSoapMessage;

    36 

    37 /**

    38  *  This class implements the interface MContentHandler required by a client of the xml framework

    39  *  It is designed to be used by xml parser that generates events using callback methods

    40  *

    41  *  @since Series60 2.6

    42  */

    43 

    44 using namespace Xml;

    45 

    46 NONSHARABLE_CLASS( CUpnpContentHandlersController ) :

    47     public CBase, public MContentHandler

    48     {

    49 public:

    50     /**

    51      * Destructor

    52      */

    53     virtual ~CUpnpContentHandlersController();

    54 

    55     /**

    56      * Two-phased constructor

    57      * @since Series60 3.2

    58      * @return instance of CUpnpContentHandlersController class

    59      */

    60     IMPORT_C static CUpnpContentHandlersController* NewL();

    61 

    62     /**

    63      * Two-phased constructor. Leaves the object on CleanupStack

    64      * @since Series60 3.2

    65      * @return instance of CUpnpContentHandlersController class

    66      */

    67     IMPORT_C static CUpnpContentHandlersController* NewLC();

    68 

    69     /**

    70     * For internal use. Update all necessary information from a SOAP-message

    71     * that should be OK answer (e.g. received by Http 200 OK message).

    72     * @param aMessage SOAP response message

    73     * @param aAction an action to update

    74     */

    75     IMPORT_C void UpdateActionWithOKResponseL( CUpnpSoapMessage* aMessage,

    76         CUpnpAction* aAction );

    77 

    78     /**

    79      * For internal use. Update all necessary information from a SOAP-message

    80      * that should contain SOAP error (fault) message (eg. received by http

    81      * 500 InternalServerError message.

    82      * @param aMessage SOAP response message

    83      * @param aAction an action to update

    84      */

    85     IMPORT_C void UpdateActionWithErrorResponseL( CUpnpSoapMessage* aMessage,

    86             CUpnpAction* aAction );

    87 

    88     /**

    89     * For internal use. Attaches the information contained in a GENA buffer

    90     * to this service. In practice, this means handling of received

    91     * GENA messages.

    92     * @since Series60 3.2

    93     * @param aGenaNotify gena notify body to be attached,

    94     * @param aService service which gena will be atached to

    95     */

    96     IMPORT_C void AttachL( const TDesC8& aGenaNotify, CUpnpService& aService );

    97 

    98     /**

    99      * Parses an xml document and returns object of CUpnpService class

   100      * It is used for the first time the xml document is parsed

   101      * @since Series60 3.2

   102      * @param aDescription xml content

   103      * @param aParentDevice parent device

   104      * @return instance of CUpnpService class

   105      */

   106     IMPORT_C CUpnpService* ParseServiceL( const TDesC8& aDescription,

   107         CUpnpDevice* aParentDevice );

   108 

   109     /**

   110     * Parses an xml document

   111     * It is used in case when CUpnpService object already exists

   112     * @since Series60 3.2

   113     * @param aDescription xml content

   114     * @param aService service pointer [in-out param]

   115     */

   116     IMPORT_C void ParseServiceL( const TDesC8& aDescription, CUpnpService* aService );

   117 

   118     /**

   119     * Parses an xml document and returns instance of CUpnpDevice class

   120     * It is used for the first time the device xml document is parsed

   121     * @since Series60 3.2

   122     * @param aDescription xml content

   123     * @return instance of CUpnpDevice class

   124     */

   125     IMPORT_C CUpnpDevice* ParseDeviceL( const TDesC8& aDescription );

   126 

   127     /**

   128     * Parses an xml document and returns instance of CUpnpDevice class

   129     * It is used in case when CUpnpDevice object already exists and update of device

   130     * xml is required

   131     * @since Series60 3.2

   132     * @param aDescription xml content

   133     * @param aDevice pointer [in-out param]

   134     */

   135     IMPORT_C void ParseDeviceL( const TDesC8& aDescription, CUpnpDevice* aDevice );

   136 

   137     /**

   138     * Parses an xml document and returns instance of CUpnpDeviceImplementation class

   139     * It is used for the first time the device xml document is parsed

   140     * @since Series60 3.2

   141     * @param aDescription xml content

   142     * @return instance of CUpnpDeviceImplementation class

   143     */

   144     IMPORT_C CUpnpDeviceImplementation* ParseDeviceImplL( const TDesC8& aDescription );

   145 

   146     /**

   147     * Parses an xml document and returns instance of CUpnpDeviceImplementation class

   148     * It is used in case when CUpnpDeviceImplementation object already exists and

   149     * update of device xml is required

   150     * @since Series60 3.2

   151     * @param aDescription xml content

   152     * @param aDevice pointer [in-out param]

   153     */

   154     IMPORT_C void ParseDeviceImplL( const TDesC8& aDescription,

   155         CUpnpDeviceImplementation* aDeviceImpl );

   156 

   157     /**

   158     * Parses an xml document and returns instance of CUpnpSilentDeviceImplementation class

   159     * It is used for the first time the device xml document is parsed

   160     * @since Series60 3.2

   161     * @param aDescription xml content

   162     * @return instance of CUpnpDeviceImplementation class

   163     */

   164     IMPORT_C CUpnpSilentDeviceImplementation* ParseSilentDeviceImplL( const TDesC8& aDescription );

   165 

   166     /**

   167     * Parses an xml document and returns instance of CUpnpSilentDeviceImplementation class

   168     * It is used in case when CUpnpDeviceImplementation object already exists and

   169     * update of device xml is required

   170     * @since Series60 3.2

   171     * @param aDescription xml content

   172     * @param aDevice pointer [in-out param]

   173     */

   174     IMPORT_C void ParseSilentDeviceImplL( const TDesC8& aDescription,

   175         CUpnpSilentDeviceImplementation* aDeviceImpl );

   176 

   177     /**

   178     * Update action with all necessary information from

   179     * a SOAP request message.

   180     * @since Series60 3.2

   181     * @param aMessage SOAP request message

   182     * @param aAction - an action to update

   183     */

   184     void UpdateActionWithRequestL( CUpnpSoapMessage* aMessage, CUpnpAction* aAction );

   185 

   186     /**

   187     * Parses a xml document and returns set objects of CUpnpDescriptionProperties

   188     * It is used to parse action messages (soap)

   189     * @pre description property array should be leave safe

   190     * (there will be PopAndDestroy called on it in case of leave)

   191     */

   192     void ParseSoapL(

   193             const TDesC8& aDescription,

   194             RPointerArray<CUpnpDescriptionProperty>& aParsedValues );

   195 

   196     /**

   197      * Sets ContentHandler argument as a current content handler, so it will

   198      * receive parsing events. Previous content handler will be push on stack

   199      * that it could be againt current content handler after calling of

   200      * SetPreviousContentHandler.

   201      * @since Series60 3.2

   202      * @param aNewContentHandler content handler that will receive all parsing events

   203      *   untill current content handler will be changed

   204      */

   205     void SetCurrentContentHandlerL( CUpnpContentHandler* aNewContentHandler );

   206 

   207     /**

   208      * Deletes current content handler, and sets previous content handler to become current

   209      * contetnt handler, and receive all sax parsing events.

   210      * @since Series60 3.2

   211      */

   212     void SetPreviousContentHandler();

   213 

   214 private: // from MContentHandler

   215 

   216     /**

   217      * This method is a callback to indicate the start of the document.

   218      * @param				aDocParam Specifies the various parameters of the document.

   219      * @arg				aDocParam.iCharacterSetName The character encoding of the document.

   220      * @param				aErrorCode is the error code.

   221      * 					If this is not KErrNone then special action may be required.

   222      */

   223     virtual void OnStartDocumentL( const RDocumentParameters& aDocParam,

   224         TInt aErrorCode );

   225 

   226     /**

   227      * This method is a callback to indicate the end of the document.

   228      * @param				aErrorCode is the error code.

   229      * 				If this is not KErrNone then special action may be required.

   230      */

   231     virtual void OnEndDocumentL( TInt aErrorCode );

   232 

   233     /**

   234      * This method is a callback to indicate an element has been parsed.

   235      * @param              aElement is a handle to the element's details.

   236      * @param              aAttributes contains the attributes for the element.

   237      * @param              aErrorCode is the error code.

   238      *                If this is not KErrNone then special action may be required.

   239      */

   240     virtual void OnStartElementL( const RTagInfo& aElement,

   241         const RAttributeArray& aAttributes, TInt aErrorCode );

   242 

   243     /**

   244      * This method is a callback to indicate the end of the element has been reached.

   245      * @param              aElement is a handle to the element's details.

   246      * @param              aErrorCode is the error code.

   247      *                If this is not KErrNone then special action may be required.

   248      */

   249     virtual void OnEndElementL( const RTagInfo& aElement, TInt aErrorCode );

   250 

   251     /**

   252      * This method is a callback that sends the content of the element.

   253      * Not all the content may be returned in one go. The data may be sent in chunks.

   254      * This method just append chunk to chunks previously received. When we get all

   255      * chunks ChunksMergingEndL method pass merged chunks to current content handler.

   256      * @param              aBytes is the raw content data for the element.

   257      *                 The client is responsible for converting the data to the

   258      *                 required character set if necessary.

   259      *                 In some instances the content may be binary and must not be converted.

   260      * @param              aErrorCode is the error code.

   261      *                If this is not KErrNone then special action may be required.

   262      */

   263     virtual void OnContentL( const TDesC8& aBytes, TInt aErrorCode );

   264 

   265     /**

   266      * This method is a notification of the beginning of the scope of a prefix-URI Namespace mapping.

   267      * This method is always called before the corresponding OnStartElementL method.

   268      * @param				aPrefix is the Namespace prefix being declared.

   269      * @param				aUri is the Namespace URI the prefix is mapped to.

   270      * @param				aErrorCode is the error code.

   271      * 				If this is not KErrNone then special action may be required.

   272      */

   273     virtual void OnStartPrefixMappingL( const RString& aPrefix,

   274         const RString& aUri, TInt aErrorCode );

   275 

   276     /**

   277      * This method is a notification of the end of the scope of a prefix-URI mapping.

   278      * This method is called after the corresponding DoEndElementL method.

   279      * @param				aPrefix is the Namespace prefix that was mapped.

   280      * @param				aErrorCode is the error code.

   281      * 				If this is not KErrNone then special action may be required.

   282      */

   283     virtual void OnEndPrefixMappingL( const RString& aPrefix, TInt aErrorCode );

   284 

   285     /**

   286      * This method is a notification of ignorable whitespace in element content.

   287      * @param				aBytes are the ignored bytes from the document being parsed.

   288      * @param				aErrorCode is the error code.

   289      * 				If this is not KErrNone then special action may be required.

   290      */

   291     virtual void OnIgnorableWhiteSpaceL( const TDesC8& aBytes, TInt aErrorCode );

   292 

   293     /**

   294      * This method is a notification of a skipped entity. If the parser encounters an

   295      * external entity it does not need to expand it - it can return the entity as aName

   296      * for the client to deal with.

   297      * @param				aName is the name of the skipped entity.

   298      * @param				aErrorCode is the error code.

   299      * 				If this is not KErrNone then special action may be required.

   300      */

   301     virtual void OnSkippedEntityL( const RString& aName, TInt aErrorCode );

   302 

   303     /**

   304      This method is a receive notification of a processing instruction.

   305      * @param				aTarget is the processing instruction target.

   306      * @param				aData is the processing instruction data. If empty none was supplied.

   307      * @param				aErrorCode is the error code.

   308      * 				If this is not KErrNone then special action may be required.

   309      */

   310     virtual void OnProcessingInstructionL( const TDesC8& aTarget,

   311         const TDesC8& aData, TInt aErrorCode );

   312 

   313     /**

   314      * This method indicates an error has occurred.

   315      * @param				aError is the error code

   316      */

   317     virtual void OnError( TInt aErrorCode );

   318 

   319     /**

   320      * This method obtains the interface matching the specified uid.

   321      * @return				0 if no interface matching the uid is found.

   322      * 				Otherwise, the this pointer cast to that interface.

   323      * @param				aUid the uid identifying the required interface.

   324      */

   325     virtual TAny* GetExtendedInterface( const TInt32 aUid );

   326     

   327     /**

   328      * This method removes forbidden characters from description     

   329      * @param				aDescription to be modified

   330      */

   331     void RemoveForbiddenCharacters( TDes8& aDescription );

   332 

   333 private:

   334 

   335     /**

   336      * Default C++ constructor

   337      */

   338     CUpnpContentHandlersController();

   339 

   340     /**

   341      * 2nd phase constructor

   342      */

   343     void ConstructL();

   344 

   345     /**

   346     * Parses a xml document and returns set objects of CUpnpDescriptionProperties

   347     * It is used to parse event notification

   348     * @pre description property array should be leave safe

   349     * (there will be PopAndDestroy called on it in case of leave)

   350     */

   351     void ParseGenaL(

   352             const TDesC8& aDescription,

   353             RPointerArray<CUpnpDescriptionProperty>& aParsedValues );

   354 

   355     /**

   356     * Parses a xml document by passed content handler

   357     * there is a guarantee that aHandlerToUse will be deleted in case of leave

   358     * @param aDescription description in xml

   359     * @param aHandlerToUse content handler that will be used to parsing

   360     * @pre: iStack is empty

   361     * @post: iStack is empty

   362     */

   363     void ParseXmlL( const TDesC8& aDescription, CUpnpContentHandler* aHandlerToUse );

   364 

   365     /**

   366      * Method that is called when all chunks that contain current content

   367      * were received, so we can pass merged content to current content handler

   368      * as an argument of OnContentL method

   369      */

   370     void ChunksMergingEndL();

   371 

   372     /**

   373     * Common code for CUpnpDevice, and CUpnpDeviceImplementation objects

   374     */

   375     template<class T>

   376     T* DoParseDeviceL( const TDesC8& aDescription, T* aDevice );

   377 

   378 private:

   379     CUpnpContentHandler* iCurrentContentHandler;

   380     //must always be equals to iStack.Head() kept here for performance and clarity reasons

   381 

   382     CParser* iParser;

   383     CStack<CUpnpContentHandler, ETrue>* iStack;

   384     RBuf8 iContent;

   385     TPtrC8 iCorrectUri;

   386 

   387     /**

   388      * The flag contains information if OnStartDocumentL were invoked

   389      * It isn't invoked f.e if xml document is empty

   390      */

   391     TBool iDocStarted;

   392 

   393     /**

   394      * Object responsible for soap parsing logic

   395      */

   396     TUpnpSoapParser iSoapParser;

   397 

   398     };

   399 

   400 #endif //__UPNPCONTENTHANDLERSCONTROLLER_H__